การใช้ Java SDK Library

แพลตฟอร์ม Android มีไลบรารี Java ที่แชร์จำนวนมาก ซึ่งสามารถเลือกรวมไว้ใน classpath ของแอปด้วยแท็ก <uses-library> ในรายการแอป แอปเชื่อมโยงกับไลบรารีเหล่านี้ ดังนั้นให้ปฏิบัติต่อไลบรารีเหล่านี้เหมือนกับส่วนที่เหลือของ Android API ในแง่ของความเข้ากันได้ การตรวจสอบ API และการสนับสนุนเครื่องมือ อย่างไรก็ตาม โปรดทราบว่าไลบรารีส่วนใหญ่ไม่มีคุณลักษณะเหล่านี้

ประเภทโมดูล java_sdk_library ช่วยจัดการไลบรารีประเภทนี้ ผู้ผลิตอุปกรณ์สามารถใช้กลไกนี้สำหรับไลบรารี Java ที่แชร์ของตนเอง เพื่อรักษาความเข้ากันได้แบบย้อนหลังสำหรับ API ของตน หากผู้ผลิตอุปกรณ์ใช้ไลบรารี Java ที่แบ่งใช้ของตนเองผ่านแท็ก <uses-library> แทนพาธ java_sdk_library สามารถตรวจสอบว่าไลบรารี Java เหล่านั้นเสถียร API

java_sdk_library ใช้ SDK API ที่เป็นตัวเลือกสำหรับแอป ไลบรารีที่ใช้งานผ่าน java_sdk_library ในไฟล์บิลด์ของคุณ ( Android.bp ) ดำเนินการดังต่อไปนี้:

• ไลบรารี stubs ถูกสร้างขึ้นเพื่อรวม stubs , stubs.system และ stubs.test ไลบรารีต้นขั้วเหล่านี้สร้างขึ้นโดยการจดจำคำอธิบายประกอบ @hide , @SystemApi และ @TestApi
• java_sdk_library จัดการไฟล์ข้อกำหนด API (เช่น current.txt ) ในไดเร็กทอรีย่อย API ไฟล์เหล่านี้ได้รับการตรวจสอบเทียบกับโค้ดล่าสุดเพื่อให้แน่ใจว่าเป็นเวอร์ชันล่าสุด หากไม่เป็นเช่นนั้น คุณจะได้รับข้อความแสดงข้อผิดพลาดที่อธิบายวิธีอัปเดต ตรวจสอบการเปลี่ยนแปลงการอัปเดตทั้งหมดด้วยตนเองเพื่อให้แน่ใจว่าตรงกับความคาดหวังของคุณ
  
  หากต้องการอัปเดต API ทั้งหมด ให้ใช้ m update-api หากต้องการตรวจสอบว่า API เป็นปัจจุบัน ให้ใช้ m checkapi
• ไฟล์ข้อกำหนด API ได้รับการตรวจสอบเทียบกับ Android เวอร์ชันล่าสุดที่เผยแพร่เพื่อให้แน่ใจว่า API นั้นเข้ากันได้กับรุ่นก่อนหน้า โมดูล java_sdk_library ที่ให้ไว้เป็นส่วนหนึ่งของ AOSP จะวางเวอร์ชันที่เผยแพร่ก่อนหน้านี้ใน prebuilts/sdk/<latest number>
• สำหรับการตรวจสอบไฟล์ข้อกำหนด API คุณสามารถทำสิ่งใดสิ่ง หนึ่ง ต่อไปนี้:
• ให้ดำเนินการตรวจสอบต่อไป (อย่าทำอะไรเลย)
• ปิดใช้งานการตรวจสอบโดยเพิ่มสิ่งต่อไปนี้ใน java_sdk_library :
  unsafe_ignore_missing_latest_api: true,
• จัดเตรียม API ที่ว่างเปล่าสำหรับโมดูล java_sdk_library ใหม่โดยสร้างไฟล์ข้อความเปล่าชื่อ module_name.txt ในไดเร็กทอรี version/scope/api
• หากมีการติดตั้งไลบรารีการนำไปใช้สำหรับรันไทม์ ไฟล์ XML จะถูกสร้างและติดตั้ง

java_sdk_library ทำงานอย่างไร

java_sdk_library ชื่อ X สร้างสิ่งต่อไปนี้:

1. ไลบรารีการใช้งานสองชุด: ไลบรารีหนึ่งชื่อ X และอีกไลบรารีหนึ่งเรียกว่า X.impl Library X ได้รับการติดตั้งบนอุปกรณ์ Library X.impl อยู่ที่นั่นก็ต่อเมื่อจำเป็นต้องมีการเข้าถึงไลบรารีการนำไปใช้อย่างชัดแจ้งโดยโมดูลอื่น ๆ เช่นสำหรับใช้ในการทดสอบ โปรดทราบว่าแทบไม่จำเป็นต้องมีการเข้าถึงอย่างชัดแจ้ง
2. สามารถเปิดและปิดขอบเขตเพื่อปรับแต่งการเข้าถึงได้ (คล้ายกับโมดิฟายเออร์การเข้าถึงคีย์เวิร์ด Java ขอบเขตสาธารณะให้การเข้าถึงที่หลากหลาย ขอบเขตการทดสอบประกอบด้วย API ที่ใช้ในการทดสอบเท่านั้น) สำหรับแต่ละขอบเขตที่เปิดใช้งาน ไลบรารีจะสร้างสิ่งต่อไปนี้:
• โมดูลต้นขั้วต้นขั้ว (ประเภทโมดูล droidstubs ) - ใช้แหล่งที่มาของการใช้งานและส่งออกชุดแหล่งที่มาของต้นขั้วพร้อมกับไฟล์ข้อกำหนด API
• ไลบรารี stubs (ประเภทโมดูล java_library ) - เป็นเวอร์ชันที่คอมไพล์แล้วของ stubs libs ที่ใช้ในการคอมไพล์สิ่งนี้ไม่เหมือนกับที่จัดหาให้กับ java_sdk_library ซึ่งทำให้แน่ใจได้ว่ารายละเอียดการใช้งานจะไม่รั่วไหลไปยังต้นขั้ว API
• หากคุณต้องการไลบรารีเพิ่มเติมเพื่อคอมไพล์ stub ให้ใช้คุณสมบัติ stub_only_libs และ stub_only_static_libs เพื่อจัดหา

หาก java_sdk_library เรียกว่า “ X ” และกำลังคอมไพล์เป็น “ X ” ให้อ้างถึงแบบนั้นเสมอและอย่าแก้ไข บิลด์จะเลือกไลบรารีที่เหมาะสม เพื่อให้แน่ใจว่าคุณมีไลบรารีที่เหมาะสมที่สุด ให้ตรวจสอบ stub ของคุณเพื่อดูว่าบิลด์มีข้อผิดพลาดหรือไม่ ทำการแก้ไขที่จำเป็นโดยใช้คำแนะนำนี้:

• ตรวจสอบว่าคุณมีไลบรารีที่เหมาะสมโดยดูจากบรรทัดคำสั่งและตรวจสอบว่ามี stub ใดอยู่ในรายการเพื่อกำหนดขอบเขตของคุณ:
• ขอบเขตกว้างเกินไป: ไลบรารีที่เกี่ยวข้องต้องการขอบเขตของ API บางอย่าง แต่คุณเห็น API ที่รวมอยู่ในไลบรารีที่อยู่นอกขอบเขตนั้น เช่น API ของระบบที่รวมอยู่ใน API สาธารณะ
• ขอบเขตแคบเกินไป: ไลบรารีขึ้นอยู่กับไม่มีการเข้าถึงไลบรารีที่จำเป็นทั้งหมด ตัวอย่างเช่น ไลบรารีที่เกี่ยวข้องจำเป็นต้องใช้ API ของระบบ แต่ได้รับ API สาธารณะแทน ซึ่งมักส่งผลให้เกิดข้อผิดพลาดในการรวบรวมเนื่องจากขาด API ที่จำเป็น
• ในการแก้ไขไลบรารี ให้ทำอย่าง ใดอย่างหนึ่ง ต่อไปนี้:
• เปลี่ยน sdk_version เพื่อเลือกเวอร์ชันที่คุณต้องการ หรือ
• ระบุไลบรารีที่เหมาะสมอย่างชัดเจน เช่น <X>.stubs หรือ <X>.stubs.system

java_sdk_library X การใช้งาน

ไลบรารีการใช้งาน X ถูกใช้เมื่อมีการอ้างอิงจาก apex.java_libs อย่างไรก็ตาม เนื่องจากข้อจำกัดของ Soong เมื่อไลบรารี X ถูกอ้างอิงจากโมดูล java_sdk_library อื่น ภายในไลบรารี APEX เดียวกัน X.impl จะต้องถูกใช้ อย่างชัดเจน ไม่ใช่ไลบรารี X

เมื่อมีการอ้างอิง java_sdk_library จากที่อื่น ไลบรารีต้นขั้วจะถูกใช้ ไลบรารี stubs ถูกเลือกตามการตั้งค่าคุณสมบัติ sdk_version ของโมดูลที่เกี่ยวข้อง ตัวอย่างเช่น โมดูลที่ระบุ sdk_version: "current" ใช้ stub สาธารณะ ในขณะที่โมดูลที่ระบุ sdk_version: "system_current" จะใช้ stub ของระบบ หากไม่พบการจับคู่แบบตรงทั้งหมด ระบบจะใช้ไลบรารีต้นขั้วที่ใกล้เคียงที่สุด java_sdk_library ที่ให้บริการ API สาธารณะเท่านั้นจะจัดหา stub สาธารณะสำหรับทุกคน

ตัวอย่างและที่มา

คุณสมบัติ srcs และ api_packages ต้อง มีอยู่ใน java_sdk_library

java_sdk_library {
        name: "com.android.future.usb.accessory",
        srcs: ["src/**/*.java"],
        api_packages: ["com.android.future.usb"],
    }

AOSP แนะนำ (แต่ไม่ต้องการ) ว่าอินสแตนซ์ java_sdk_library ใหม่เปิดใช้งานขอบเขต API ที่ต้องการใช้อย่างชัดเจน คุณยังสามารถ (เป็นทางเลือก) โยกย้ายอินสแตนซ์ java_sdk_library ที่มีอยู่เพื่อเปิดใช้งานขอบเขต API อย่างชัดเจนที่จะใช้:

java_sdk_library {
         name: "lib",
         public: {
           enabled: true,
         },
         system: {
           enabled: true,
         },
         …
    }

ในการกำหนดค่าไลบรารี impl ที่ใช้สำหรับรันไทม์ ให้ใช้คุณสมบัติ java_library ปกติทั้งหมด เช่น hostdex , compile_dex และ errorprone

java_sdk_library {
        name: "android.test.base",

        srcs: ["src/**/*.java"],

        errorprone: {
          javacflags: ["-Xep:DepAnn:ERROR"],
        },

        hostdex: true,

        api_packages: [
            "android.test",
            "android.test.suitebuilder.annotation",
            "com.android.internal.util",
            "junit.framework",
        ],

        compile_dex: true,
    }

ในการกำหนดค่าไลบรารี stubs ให้ใช้คุณสมบัติต่อไปนี้:

• merge_annotations_dirs และ merge_inclusion_annotations_dirs
• api_srcs : รายการของไฟล์ซอร์สทางเลือกที่เป็นส่วนหนึ่งของ API แต่ไม่ใช่ส่วนหนึ่งของไลบรารีรันไทม์
• stubs_only_libs : รายการไลบรารี Java ที่อยู่ใน classpath เมื่อสร้าง stub
• hidden_api_packages : รายการชื่อแพ็คเกจที่ต้องซ่อนจาก API
• droiddoc_options : อาร์กิวเมนต์เพิ่มเติมสำหรับ metalava
• droiddoc_option_files : แสดงรายการไฟล์ที่สามารถอ้างอิงได้จากภายใน droiddoc_options โดยใช้ $(location <label>) โดยที่ <file> เป็นรายการในรายการ
• annotations_enabled

java_sdk_library เป็น java_library แต่มันไม่ใช่โมดูล droidstubs ดังนั้นจึงไม่รองรับคุณสมบัติของ droidstubs ทั้งหมด ตัวอย่างต่อไปนี้นำมาจากไฟล์ build ไลบรารี android.test.mock

java_sdk_library {
        name: "android.test.mock",

        srcs: [":android-test-mock-sources"],
        api_srcs: [
            // Note: The following aren’t APIs of this library. Only APIs under the
            // android.test.mock package are taken. These do provide private APIs
            // to which android.test.mock APIs reference. These classes are present
            // in source code form to access necessary comments that disappear when
            // the classes are compiled into a Jar library.
            ":framework-core-sources-for-test-mock",
            ":framework_native_aidl",
        ],

        libs: [
            "framework",
            "framework-annotations-lib",
            "app-compat-annotations",
            "Unsupportedappusage",
        ],

        api_packages: [
            "android.test.mock",
        ],
        permitted_packages: [
            "android.test.mock",
        ],
        compile_dex: true,
        default_to_stubs: true,
    }

รักษาความเข้ากันได้ย้อนหลัง

ระบบบิลด์จะตรวจสอบว่า API รักษาความเข้ากันได้แบบย้อนหลังหรือไม่โดยเปรียบเทียบไฟล์ API ล่าสุดกับไฟล์ API ที่สร้างขึ้น ณ เวลาสร้าง java_sdk_library ดำเนินการตรวจสอบความเข้ากันได้โดยใช้ข้อมูลที่ได้รับจาก prebuilt_apis ไลบรารีทั้งหมดที่สร้างด้วย java_sdk_library ต้องมีไฟล์ API ในเวอร์ชันล่าสุดของ api_dirs ใน prebuilt_apis เมื่อคุณเผยแพร่เวอร์ชัน API จะแสดงรายการไฟล์และไลบรารีต้นขั้วที่สามารถรับได้ด้วย dist build ด้วย PRODUCT=sdk_phone_armv7-sdk

คุณสมบัติ api_dirs คือรายการของไดเร็กทอรีเวอร์ชัน API ใน prebuilt_apis ไดเรกทอรีเวอร์ชัน API ต้องอยู่ที่ระดับไดเรกทอรี Android.bp

prebuilt_apis {
       name: "foo",
       api_dirs: [
           "1",
           "2",
             ....
           "30",
           "current",
       ],
    }

กำหนดค่าไดเร็กทอรีด้วยโครงสร้าง version / scope /api/ ภายใต้ไดเร็กทอรีที่สร้างไว้ล่วงหน้า version สอดคล้องกับระดับ API และ scope กำหนดว่าไดเร็กทอรีเป็นแบบสาธารณะ ระบบ หรือแบบทดสอบ

• version / scope มีไลบรารี Java
• version / scope /api มีไฟล์ API .txt สร้างไฟล์ข้อความเปล่าชื่อ module_name .txt และ module_name -removed.txt ที่นี่

   ├── 30
        │   ├── public
        │   │   ├── api
        │   │   │   ├── android.test.mock-removed.txt
        │   │   │   └── android.test.mock.txt
        │   │   └── android.test.mock.jar
        │   ├── system
        │   │   ├── api
        │   │   │   ├── android.test.mock-removed.txt
        │   │   │   └── android.test.mock.txt
        │   │   └── android.test.mock.jar
        │   └── test
        │       ├── api
        │       │   ├── android.test.mock-removed.txt
        │       │   └── android.test.mock.txt
        │       └── android.test.mock.jar
        └── Android.bp