ใช้ไลบรารี Java SDK

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

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

java_sdk_library ใช้ SDK API ที่ไม่บังคับเพื่อการใช้งานโดย แอป ไลบรารีที่ติดตั้งใช้งานผ่าน java_sdk_library ใน ไฟล์บิลด์ (Android.bp) จะดำเนินการต่อไปนี้

• ไลบรารีสตับสร้างขึ้นเพื่อรวม 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 คุณสามารถทําได้ 1 จาก 3 รายการต่อไปนี้
• อนุญาตให้ตรวจสอบเพื่อดำเนินการต่อ (ไม่ต้องดำเนินการใดๆ)
• ปิดใช้การตรวจสอบโดยเพิ่มข้อมูลต่อไปนี้ใน 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. ไลบรารีการใช้งาน 2 ชุด ได้แก่ ไลบรารี 1 ชุดที่ชื่อ X และอีกอันเรียกว่า X.impl ติดตั้งไลบรารี X แล้ว ในอุปกรณ์ ไลบรารี X.impl จะใช้ได้เฉพาะเมื่อการเข้าถึงอย่างชัดเจน โมดูลอื่นๆ จำเป็นต้องมีไลบรารีการนำไปใช้ เช่น เพื่อใช้ใน การทดสอบ โปรดทราบว่าการเข้าถึงอย่างชัดแจ้งมักไม่จำเป็น
2. คุณเปิดและปิดใช้ขอบเขตเพื่อปรับแต่งการเข้าถึงได้ (คล้ายกับ Java ตัวแก้ไขการเข้าถึงคำหลัก ขอบเขตสาธารณะจะให้การเข้าถึงที่กว้างขวาง CANNOT TRANSLATE ขอบเขตการทดสอบมี API ที่ใช้ในการทดสอบเท่านั้น) สำหรับแต่ละขอบเขตที่เปิดใช้ ค่า ไลบรารีจะสร้างสิ่งต่อไปนี้
• โมดูลต้นทางของต้นขั้ว (ของโมดูล droidstubs ประเภท) - ใช้ แหล่งที่มาของการใช้งานและแสดงชุดซอร์สของสตับพร้อมด้วย ไฟล์ข้อกำหนด API
• ไลบรารีต้นขั้ว (ของโมดูล java_library ประเภท) - คือค่า เวอร์ชันสะสมของต้นขั้ว ไลบรารีที่ใช้คอมไพล์นี้ไม่ใช่ เหมือนกับค่าที่ส่งไปยัง java_sdk_library เพื่อให้ รายละเอียดการใช้งานไม่รั่วไหลออกไปในสตับ API
• หากคุณต้องการไลบรารีเพิ่มเติมเพื่อคอมไพล์สตับ ให้ใช้ stub_only_libs และ stub_only_static_libs คุณสมบัติที่เหมาะสม

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

• ตรวจสอบว่าคุณมีไลบรารีที่เหมาะสมโดยดูที่บรรทัดคำสั่งและ ตรวจสอบว่าต้นขั้วรายการใดแสดงอยู่เพื่อกำหนดขอบเขตของคุณ ดังนี้
• ขอบเขตกว้างเกินไป: ไลบรารีที่ขึ้นอยู่กับต้องการขอบเขต 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 จากที่อื่น สตับ และไลบรารีที่ใช้ร่วมกัน เลือกไลบรารีต้นขั้วตาม การตั้งค่าพร็อพเพอร์ตี้ของโมดูล sdk_version เช่น โมดูลที่ ระบุ sdk_version: "current" ใช้ต้นขั้วสาธารณะ ขณะที่ ที่ระบุว่า sdk_version: "system_current" ใช้เมธอด ต้นขั้วระบบ หากไม่พบรายการที่ตรงกันทั้งหมด ไลบรารีต้นขั้วที่อยู่ใกล้ที่สุดจะได้รับ ที่ใช้ java_sdk_library ที่ระบุเฉพาะ API สาธารณะจะ ช่วยมอบอำนาจสาธารณะให้กับทุกคน

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

พร็อพเพอร์ตี้ 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 เมื่อสร้างต้นขั้ว
• hidden_api_packages: รายการชื่อแพ็กเกจที่ต้อง ซ่อนจาก API
• droiddoc_options: อาร์กิวเมนต์เพิ่มเติมสำหรับ metalava
• droiddoc_option_files: แสดงไฟล์ที่สามารถอ้างอิงได้ จากภายใน droiddoc_options โดยใช้ $(location <label>) โดยที่ <file> เป็นรายการในรายการ
• annotations_enabled

java_sdk_library เป็น java_library แต่ไม่ใช่ ดังนั้นโมดูล droidstubs จึงไม่รองรับ droidstubs ทั้งหมด พร็อพเพอร์ตี้ ตัวอย่างต่อไปนี้มาจาก บิลด์ไลบรารี 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 จะแสดงไฟล์และสตับ รับไลบรารีได้ด้วยบิลด์ที่ห่างไกลด้วย 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