जावा एसडीके लाइब्रेरी को लागू करना

एंड्रॉइड प्लेटफ़ॉर्म में बड़ी संख्या में साझा जावा लाइब्रेरी शामिल हैं जिन्हें ऐप मेनिफेस्ट में <uses-library> टैग के साथ ऐप के क्लासपाथ में वैकल्पिक रूप से शामिल किया जा सकता है। ऐप्स इन लाइब्रेरीज़ के विरुद्ध लिंक करते हैं, इसलिए अनुकूलता, एपीआई समीक्षा और टूलींग समर्थन के मामले में उन्हें बाकी एंड्रॉइड एपीआई की तरह ही मानें। हालाँकि, ध्यान दें कि अधिकांश पुस्तकालयों में ये सुविधाएँ नहीं हैं।

java_sdk_library मॉड्यूल प्रकार इस प्रकार की लाइब्रेरी को प्रबंधित करने में मदद करता है। डिवाइस निर्माता अपने एपीआई के लिए बैकवर्ड संगतता बनाए रखने के लिए, अपने स्वयं के साझा जावा पुस्तकालयों के लिए इस तंत्र का उपयोग कर सकते हैं। यदि डिवाइस निर्माता बूटक्लास पथ के बजाय <uses-library> टैग के माध्यम से अपनी स्वयं की साझा जावा लाइब्रेरी का उपयोग करते हैं, तो java_sdk_library सत्यापित कर सकता है कि वे जावा लाइब्रेरी एपीआई-स्थिर हैं।

java_sdk_library ऐप्स द्वारा उपयोग के लिए वैकल्पिक SDK API लागू करता है। आपकी बिल्ड फ़ाइल ( Android.bp ) में java_sdk_library के माध्यम से कार्यान्वित लाइब्रेरीज़ निम्नलिखित कार्य करती हैं:

  • स्टब्स पुस्तकालयों को stubs , stubs.system और stubs.test शामिल करने के लिए तैयार किया जाता है। ये स्टब्स लाइब्रेरी @hide , @SystemApi और @TestApi एनोटेशन को पहचानकर बनाई गई हैं।
  • java_sdk_library एक एपीआई उपनिर्देशिका में एपीआई विनिर्देश फ़ाइलों (जैसे कि current.txt ) का प्रबंधन करता है। यह सुनिश्चित करने के लिए कि ये नवीनतम संस्करण हैं, इन फ़ाइलों की नवीनतम कोड से जाँच की जाती है। यदि वे नहीं हैं, तो आपको एक त्रुटि संदेश प्राप्त होता है जो बताता है कि उन्हें कैसे अपडेट किया जाए। यह सुनिश्चित करने के लिए कि वे आपकी अपेक्षाओं से मेल खाते हैं, सभी अद्यतन परिवर्तनों की मैन्युअल रूप से समीक्षा करें।

    सभी एपीआई को अपडेट करने के लिए, m update-api उपयोग करें। यह सत्यापित करने के लिए कि कोई एपीआई अद्यतित है, m checkapi उपयोग करें।
  • एपीआई विनिर्देश फ़ाइलों को सबसे हाल ही में प्रकाशित एंड्रॉइड संस्करणों के खिलाफ जांचा जाता है ताकि यह सुनिश्चित किया जा सके कि एपीआई पिछले रिलीज के साथ पिछड़े-संगत है। AOSP के भाग के रूप में प्रदान किए गए java_sdk_library मॉड्यूल अपने पहले जारी किए गए संस्करणों को prebuilts/sdk/<latest number> में रखते हैं।
  • एपीआई विनिर्देश फ़ाइलों की जांच के संबंध में, आप निम्नलिखित तीन चीजों में से एक कर सकते हैं:
    • चेक को आगे बढ़ने दें. (कुछ मत करो.)
    • java_sdk_library में निम्नलिखित जोड़कर जाँच अक्षम करें:
      unsafe_ignore_missing_latest_api: true,
    • version/scope/api निर्देशिका में module_name.txt नामक खाली टेक्स्ट फ़ाइलें बनाकर नए java_sdk_library मॉड्यूल के लिए खाली एपीआई प्रदान करें।
  • यदि रनटाइम के लिए कार्यान्वयन लाइब्रेरी स्थापित है, तो एक XML फ़ाइल उत्पन्न और स्थापित हो जाती है।

java_sdk_library कैसे काम करता है

X नामक java_sdk_library निम्नलिखित बनाता है:

  1. कार्यान्वयन लाइब्रेरी की दो प्रतियां: एक लाइब्रेरी को X कहा जाता है और दूसरी को X.impl कहा जाता है। लाइब्रेरी X डिवाइस पर स्थापित है। X.impl ध्यान दें कि स्पष्ट पहुंच की शायद ही कभी आवश्यकता होती है।
  2. पहुंच को अनुकूलित करने के लिए स्कोप को सक्षम और अक्षम किया जा सकता है। (जावा कीवर्ड-एक्सेस संशोधक के समान, एक सार्वजनिक स्कोप पहुंच की एक विस्तृत श्रृंखला प्रदान करता है; एक परीक्षण स्कोप में केवल परीक्षण में उपयोग किए जाने वाले एपीआई होते हैं।) प्रत्येक सक्षम स्कोप के लिए लाइब्रेरी निम्नलिखित बनाती है:
    • एक स्टब्स स्रोत मॉड्यूल ( droidstubs मॉड्यूल प्रकार का) - कार्यान्वयन स्रोत का उपभोग करता है और एपीआई विनिर्देश फ़ाइल के साथ स्टब स्रोतों का एक सेट आउटपुट करता है।
    • एक स्टब्स लाइब्रेरी ( java_library मॉड्यूल प्रकार की) - स्टब्स का संकलित संस्करण है। इसे संकलित करने के लिए उपयोग किए गए libs java_sdk_library को दिए गए libs के समान नहीं हैं, जो यह सुनिश्चित करता है कि कार्यान्वयन विवरण API स्टब्स में लीक न हो।
    • यदि आपको स्टब्स संकलित करने के लिए अतिरिक्त पुस्तकालयों की आवश्यकता है, तो उन्हें आपूर्ति करने के लिए stub_only_libs और stub_only_static_libs गुणों का उपयोग करें।

यदि java_sdk_library को " X " कहा जाता है, और इसे " X " के विरुद्ध संकलित किया जा रहा है, तो इसे हमेशा उसी तरह देखें और इसे संशोधित न करें। बिल्ड एक उपयुक्त लाइब्रेरी का चयन करेगा। यह सुनिश्चित करने के लिए कि आपके पास सबसे उपयुक्त लाइब्रेरी है, यह देखने के लिए अपने स्टब्स का निरीक्षण करें कि क्या बिल्ड में त्रुटियां हैं। इस मार्गदर्शन का उपयोग करके कोई भी आवश्यक सुधार करें:

  • सत्यापित करें कि आपके पास कमांड लाइन को देखकर और अपना दायरा निर्धारित करने के लिए वहां कौन से स्टब्स सूचीबद्ध हैं, इसका निरीक्षण करके एक उपयुक्त लाइब्रेरी है:
    • दायरा बहुत व्यापक है: निर्भर लाइब्रेरी को एपीआई के एक निश्चित दायरे की आवश्यकता होती है। लेकिन आप लाइब्रेरी में शामिल एपीआई देखते हैं जो उस दायरे से बाहर हैं, जैसे सार्वजनिक एपीआई के साथ शामिल सिस्टम एपीआई।
    • दायरा बहुत संकीर्ण है: निर्भर पुस्तकालय के पास सभी अपेक्षित पुस्तकालयों तक पहुंच नहीं है। उदाहरण के लिए, निर्भर लाइब्रेरी को सिस्टम एपीआई का उपयोग करने की आवश्यकता होती है लेकिन इसके बजाय उसे सार्वजनिक एपीआई मिलती है। इसके परिणामस्वरूप आमतौर पर संकलन त्रुटि होती है क्योंकि आवश्यक एपीआई गायब हैं।
  • लाइब्रेरी को ठीक करने के लिए, निम्न में से केवल एक कार्य करें:
    • आपको जिस संस्करण की आवश्यकता है उसे चुनने के लिए sdk_version बदलें। या
    • उपयुक्त लाइब्रेरी को स्पष्ट रूप से निर्दिष्ट करें, जैसे <X>.stubs या <X>.stubs.system

java_sdk_library एक्स उपयोग

कार्यान्वयन लाइब्रेरी X का उपयोग तब किया जाता है जब इसे apex.java_libs से संदर्भित किया जाता है। हालाँकि, सूंग सीमा के कारण, जब लाइब्रेरी X उसी APEX लाइब्रेरी के भीतर किसी अन्य java_sdk_library मॉड्यूल से संदर्भित किया जाता है, तो X.impl स्पष्ट रूप से उपयोग किया जाना चाहिए, न कि X

जब java_sdk_library को कहीं और से संदर्भित किया जाता है, तो एक स्टब्स लाइब्रेरी का उपयोग किया जाता है। स्टब्स लाइब्रेरी का चयन निर्भर मॉड्यूल की sdk_version प्रॉपर्टी सेटिंग के अनुसार किया जाता है। उदाहरण के लिए, एक मॉड्यूल जो sdk_version: "current" निर्दिष्ट करता है वह सार्वजनिक स्टब्स का उपयोग करता है, जबकि एक मॉड्यूल जो sdk_version: "system_current" निर्दिष्ट करता है वह सिस्टम स्टब्स का उपयोग करता है। यदि सटीक मिलान नहीं मिल पाता है, तो निकटतम स्टब लाइब्रेरी का उपयोग किया जाता है। एक java_sdk_library जो केवल एक सार्वजनिक एपीआई प्रदान करती है, सभी के लिए सार्वजनिक स्टब्स की आपूर्ति करेगी।

जावा एसडीके लाइब्रेरी के साथ प्रवाह बनाएं
चित्र 1. जावा एसडीके लाइब्रेरी के साथ प्रवाह बनाएं

उदाहरण और स्रोत

srcs और api_packages गुण java_sdk_library में मौजूद होने चाहिए

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

एओएसपी अनुशंसा करता है (लेकिन इसकी आवश्यकता नहीं है) कि नए java_sdk_library इंस्टेंस स्पष्ट रूप से उन एपीआई स्कोप को सक्षम करें जिनका वे उपयोग करना चाहते हैं। आप (वैकल्पिक रूप से) मौजूदा java_sdk_library उदाहरणों को उनके द्वारा उपयोग किए जाने वाले एपीआई स्कोप को स्पष्ट रूप से सक्षम करने के लिए माइग्रेट कर सकते हैं:

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,
    }

स्टब्स लाइब्रेरीज़ को कॉन्फ़िगर करने के लिए, निम्नलिखित गुणों का उपयोग करें:

  • merge_annotations_dirs और merge_inclusion_annotations_dirs
  • api_srcs : वैकल्पिक स्रोत फ़ाइलों की सूची जो एपीआई का हिस्सा हैं लेकिन रनटाइम लाइब्रेरी का हिस्सा नहीं हैं।
  • stubs_only_libs : जावा लाइब्रेरीज़ की सूची जो स्टब्स बनाते समय क्लासपाथ में होती हैं।
  • hidden_api_packages : पैकेज नामों की सूची जिन्हें एपीआई से छिपाया जाना चाहिए।
  • droiddoc_options : मेटालावा के लिए अतिरिक्त तर्क।
  • droiddoc_option_files : उन फ़ाइलों को सूचीबद्ध करता है जिन्हें $(location <label>) का उपयोग करके droiddoc_options के भीतर से संदर्भित किया जा सकता है, जहां <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,
    }

पश्चगामी अनुकूलता बनाए रखना

बिल्ड सिस्टम यह जांचता है कि बिल्ड समय पर जेनरेट की गई एपीआई फाइलों के साथ नवीनतम एपीआई फाइलों की तुलना करके एपीआई ने बैकवर्ड संगतता बनाए रखी है या नहीं। java_sdk_library prebuilt_apis द्वारा प्रदान की गई जानकारी का उपयोग करके संगतता जांच करता है। java_sdk_library के साथ निर्मित सभी पुस्तकालयों में prebuilt_apis में api_dirs के नवीनतम संस्करण में API फ़ाइलें होनी चाहिए। जब आप संस्करण जारी करते हैं, तो एपीआई सूची फ़ाइलें और स्टब्स लाइब्रेरीज़ को PRODUCT=sdk_phone_armv7-sdk के साथ डिस्ट बिल्ड के साथ प्राप्त किया जा सकता है।

api_dirs संपत्ति prebuilt_apis में API संस्करण निर्देशिकाओं की सूची है। एपीआई-संस्करण निर्देशिकाएं Android.bp निर्देशिका स्तर पर स्थित होनी चाहिए।

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

प्रीबिल्ट्स निर्देशिका के अंतर्गत version / scope /api/ संरचना के साथ निर्देशिकाओं को कॉन्फ़िगर करें। version एपीआई स्तर से मेल खाता है और scope परिभाषित करता है कि निर्देशिका सार्वजनिक है, सिस्टम है या परीक्षण है।

  • version / scope में जावा लाइब्रेरी शामिल हैं।
  • version / scope /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