ใช้ไลบรารี 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 สาธารณะจะ ช่วยมอบอำนาจสาธารณะให้กับทุกคน

วันที่ สร้างโฟลว์ด้วยไลบรารี 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 ที่อยู่ในไฟล์ 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