การใช้ Java SDK Library

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

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

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

  • ห้องสมุดไม่สมบูรณ์จะถูกสร้างขึ้นเพื่อรวม stubs , stubs.system และ stubs.test ห้องสมุดไม่สมบูรณ์เหล่านี้จะถูกสร้างขึ้นโดยตระหนักถึง @hide , @SystemApi และ @TestApi คำอธิบายประกอบ
  • java_sdk_library จัดการไฟล์ข้อกำหนด API (เช่น current.txt ) ในไดเรกทอรีย่อย API ไฟล์เหล่านี้ได้รับการตรวจสอบเทียบกับโค้ดล่าสุดเพื่อให้แน่ใจว่าเป็นเวอร์ชันล่าสุด หากไม่เป็นเช่นนั้น คุณจะได้รับข้อความแสดงข้อผิดพลาดที่อธิบายวิธีอัปเดต ตรวจสอบการเปลี่ยนแปลงการอัปเดตทั้งหมดด้วยตนเองเพื่อให้แน่ใจว่าตรงกับความคาดหวังของคุณ
  • ไฟล์ข้อมูลจำเพาะของ 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 ห้องสมุด X มีการติดตั้งบนอุปกรณ์ ห้องสมุด X.impl จะมีเฉพาะในกรณีที่การเข้าถึงอย่างชัดเจนไปยังห้องสมุดการดำเนินการเป็นสิ่งจำเป็นโดยโมดูลอื่น ๆ เช่นสำหรับการใช้งานในการทดสอบ โปรดทราบว่าแทบไม่จำเป็นต้องมีการเข้าถึงอย่างชัดแจ้ง
  2. สามารถเปิดและปิดขอบเขตเพื่อปรับแต่งการเข้าถึงได้ (คล้ายกับโมดิฟายเออร์การเข้าถึงคีย์เวิร์ด Java ขอบเขตสาธารณะให้การเข้าถึงที่หลากหลาย ขอบเขตการทดสอบประกอบด้วย API ที่ใช้ในการทดสอบเท่านั้น) สำหรับแต่ละขอบเขตที่เปิดใช้งาน ไลบรารีจะสร้างสิ่งต่อไปนี้:
    • ต้นขั้วโมดูลแหล่งที่มา (จาก droidstubs ประเภทโมดูล) - กินแหล่งที่มาการดำเนินการและผลชุดของแหล่งต้นขั้วพร้อมกับไฟล์ข้อมูลจำเพาะของ API
    • สมบูรณ์ห้องสมุด (จาก java_library ประเภทโมดูล) - เป็นรุ่นที่รวบรวมของไม่สมบูรณ์ libs ที่ใช้ในการรวบรวมนี้จะไม่ได้เช่นเดียวกับที่จ่ายให้กับ java_sdk_library ซึ่งทำให้มั่นใจได้รายละเอียดการดำเนินการไม่รั่วไหลเข้าไปในต้นขั้วของ API
    • หากคุณจำเป็นต้องห้องสมุดเพิ่มเติมเพื่อรวบรวมต้นขั้วใช้ 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 มีการอ้างอิงจากที่อื่น ๆ ห้องสมุดสมบูรณ์จะใช้ ห้องสมุดไม่สมบูรณ์จะถูกเลือกตามโมดูลขึ้นของ sdk_version การตั้งค่าสถานที่ให้บริการ ยกตัวอย่างเช่นโมดูลที่ระบุ sdk_version: "current" การนำมาใช้ประโยชน์ไม่สมบูรณ์ของประชาชนในขณะที่โมดูลที่ระบุ sdk_version: "system_current" ใช้ไม่สมบูรณ์ของระบบ หากไม่พบการจับคู่แบบตรงทั้งหมด ไลบรารี stub ที่ใกล้ที่สุดจะถูกใช้ java_sdk_library ว่าเพียง แต่ให้ประชาชน API จะเป็นผู้จัดหาต้นขั้วสาธารณะสำหรับทุกคน

สร้างโฟลว์ด้วยไลบรารี Java SDK
รูปที่ 1 การสร้างห้องสมุด Java SDK

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

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 ที่อยู่ในคลาสพา ธ เมื่อมีการสร้างไม่สมบูรณ์
  • 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/ โครงสร้างภายใต้ไดเรกทอรี prebuilts 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