Java SDK Kitaplığını Uygulama

Android platformu, isteğe bağlı olarak uygulama bildirimindeki <uses-library> etiketiyle uygulamaların sınıf yoluna eklenebilecek çok sayıda paylaşılan Java kitaplığı içerir. Uygulamalar bu kitaplıklara bağlanır; dolayısıyla uyumluluk, API incelemesi ve araç desteği açısından bunlara Android API'nin geri kalanı gibi davranın. Ancak çoğu kütüphanenin bu özelliklere sahip olmadığını unutmayın.

java_sdk_library modül türü bu tür kitaplıkların yönetilmesine yardımcı olur. Cihaz üreticileri, API'lerinin geriye dönük uyumluluğunu korumak amacıyla bu mekanizmayı kendi paylaşılan Java kitaplıkları için kullanabilirler. Cihaz üreticileri kendi paylaşılan Java kitaplıklarını bootclass yolu yerine <uses-library> etiketi aracılığıyla kullanıyorsa, java_sdk_library bu Java kitaplıklarının API açısından kararlı olduğunu doğrulayabilir.

java_sdk_library uygulamalar tarafından kullanılmak üzere isteğe bağlı SDK API'lerini uygular. Derleme dosyanızda ( Android.bp ) java_sdk_library aracılığıyla uygulanan kitaplıklar aşağıdaki işlemleri gerçekleştirir:

  • Taslak kitaplıkları, stubs , stubs.system ve stubs.test öğelerini içerecek şekilde oluşturulur. Bu taslak kitaplıkları, @hide , @SystemApi ve @TestApi ek açıklamalarının tanınmasıyla oluşturulur.
  • java_sdk_library bir API alt dizinindeki API belirtim dosyalarını ( current.txt gibi) yönetir. Bu dosyalar, en güncel sürüm olduklarından emin olmak için en son kodla karşılaştırılarak kontrol edilir. Değilse, bunların nasıl güncelleştirileceğini açıklayan bir hata mesajı alırsınız. Beklentilerinize uyduklarından emin olmak için tüm güncelleme değişikliklerini manuel olarak inceleyin.

    Tüm API'leri güncellemek için m update-api kullanın. Bir API'nin güncel olduğunu doğrulamak için m checkapi kullanın.
  • API spesifikasyon dosyaları, API'nin önceki sürümlerle geriye dönük olarak uyumlu olduğundan emin olmak için en son yayınlanan Android sürümleriyle karşılaştırılarak kontrol edilir. AOSP'nin bir parçası olarak sağlanan java_sdk_library modülleri, önceden yayınlanmış sürümlerini prebuilts/sdk/<latest number> içine yerleştirir.
  • API spesifikasyon dosyalarının kontrolleriyle ilgili olarak aşağıdaki üç şeyden birini yapabilirsiniz:
    • Kontrollerin devam etmesine izin verin. (Hiçbir şey yapmayın.)
    • Aşağıdakileri java_sdk_library dosyasına ekleyerek kontrolleri devre dışı bırakın:
      unsafe_ignore_missing_latest_api: true,
    • version/scope/api dizininde module_name.txt adlı boş metin dosyaları oluşturarak yeni java_sdk_library modülleri için boş API'ler sağlayın.
  • Çalışma zamanına yönelik uygulama kitaplığı kuruluysa bir XML dosyası oluşturulur ve yüklenir.

Java_sdk_library nasıl çalışır?

X adlı bir java_sdk_library aşağıdakileri oluşturur:

  1. Uygulama kitaplığının iki kopyası: X adlı bir kitaplık ve X.impl adlı bir başka kitaplık. Kitaplık X cihaza kuruludur. Kitaplık X.impl yalnızca testlerde kullanım gibi diğer modüllerin uygulama kitaplığına açık erişime ihtiyaç duyması durumunda mevcuttur. Açık erişimin nadiren gerekli olduğunu unutmayın.
  2. Erişimi özelleştirmek için kapsamlar etkinleştirilebilir ve devre dışı bırakılabilir. (Java anahtar kelime erişim değiştiricilerine benzer şekilde, genel kapsam geniş bir erişim aralığı sağlar; test kapsamı yalnızca testte kullanılan API'leri içerir.) Etkinleştirilen her kapsam için kitaplık aşağıdakileri oluşturur:
    • Bir saplama kaynak modülü ( droidstubs modül tipinde) - uygulama kaynağını tüketir ve API spesifikasyon dosyasıyla birlikte bir dizi saplama kaynağının çıktısını alır.
    • Bir taslak kütüphanesi ( java_library modül tipinde) - taslakların derlenmiş versiyonudur. Bunu derlemek için kullanılan kütüphaneler, java_sdk_library sağlananlarla aynı değildir; bu, uygulama ayrıntılarının API taslaklarına sızmamasını sağlar.
    • Saplamaları derlemek için ek kitaplıklara ihtiyacınız varsa bunları sağlamak için stub_only_libs ve stub_only_static_libs özelliklerini kullanın.

Bir java_sdk_library " X " olarak adlandırılıyorsa ve " X " olarak derleniyorsa, ona her zaman bu şekilde bakın ve onu değiştirmeyin. Derleme uygun bir kütüphane seçecektir. En uygun kitaplığa sahip olduğunuzdan emin olmak için derlemenizin hatalara yol açıp açmadığını görmek için taslaklarınızı inceleyin. Bu kılavuzu kullanarak gerekli düzeltmeleri yapın:

  • Komut satırına bakarak ve kapsamınızı belirlemek için orada hangi taslakların listelendiğini inceleyerek uygun bir kitaplığa sahip olduğunuzu doğrulayın:
    • Kapsam çok geniş: Bağlı kitaplığın belirli bir API kapsamına ihtiyacı var. Ancak, genel API'lere dahil edilen sistem API'leri gibi kitaplıkta bu kapsamın dışında kalan API'ler görüyorsunuz.
    • Kapsam çok dar: Bağlı kitaplığın gerekli tüm kitaplıklara erişimi yok. Örneğin, bağlı kitaplığın sistem API'sini kullanması gerekir ancak bunun yerine genel API'yi alır. Bu genellikle gerekli API'lerin eksik olması nedeniyle derleme hatasıyla sonuçlanır.
  • Kitaplığı düzeltmek için aşağıdakilerden yalnızca birini yapın:
    • İhtiyacınız olan sürümü seçmek için sdk_version değerini değiştirin. VEYA
    • <X>.stubs veya <X>.stubs.system gibi uygun kitaplığı açıkça belirtin.

java_sdk_library X kullanımı

Uygulama kütüphanesi X apex.java_libs referans alındığında kullanılır. Ancak Soong sınırlaması nedeniyle X kitaplığına aynı APEX kitaplığı içindeki başka bir java_sdk_library modülünden başvurulduğunda, X kitaplığı değil, açıkça X.impl kullanılmalıdır.

java_sdk_library başka bir yerden başvurulduğunda bir taslak kitaplığı kullanılır. Taslak kitaplığı, bağlı modülün sdk_version özellik ayarına göre seçilir. Örneğin, sdk_version: "current" belirten bir modül genel taslakları kullanırken, sdk_version: "system_current" değerini belirten bir modül sistem taslaklarını kullanır. Tam bir eşleşme bulunamazsa en yakın saplama kütüphanesi kullanılır. Yalnızca genel bir API sağlayan bir java_sdk_library , herkese açık taslakları sağlayacaktır.

Java SDK kitaplığıyla akış oluşturma
Şekil 1. Java SDK kitaplığıyla akış oluşturma

Örnekler ve kaynaklar

srcs ve api_packages özelliklerinin java_sdk_library bulunması gerekir .

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

AOSP, yeni java_sdk_library örneklerinin kullanmak istedikleri API kapsamlarını açıkça etkinleştirmesini önerir (ancak gerektirmez). Ayrıca (isteğe bağlı olarak) mevcut java_sdk_library örneklerini kullanacakları API kapsamlarını açıkça etkinleştirmek için taşıyabilirsiniz:

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

Çalışma zamanı için kullanılan impl kitaplığını yapılandırmak için hostdex , compile_dex ve errorprone gibi tüm normal java_library özelliklerini kullanın.

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

Saplama kitaplıklarını yapılandırmak için aşağıdaki özellikleri kullanın:

  • merge_annotations_dirs ve merge_inclusion_annotations_dirs .
  • api_srcs : API'nin parçası olan ancak çalışma zamanı kitaplığının parçası olmayan isteğe bağlı kaynak dosyalarının listesi.
  • stubs_only_libs : Saplamalar oluşturulurken sınıf yolunda bulunan Java kitaplıklarının listesi.
  • hidden_api_packages : API'den gizlenmesi gereken paket adlarının listesi.
  • droiddoc_options : Metalava için ek argüman.
  • droiddoc_option_files : $(location <label>) kullanılarak droiddoc_options içinden başvurulabilecek dosyaları listeler; burada <file> listedeki bir giriştir.
  • annotations_enabled .

java_sdk_library bir java_library , ancak bir droidstubs modülü değildir ve bu nedenle droidstubs özelliklerinin tamamını desteklemez. Aşağıdaki örnek android.test.mock kütüphanesinin derleme dosyasından alınmıştır.

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

Geriye dönük uyumluluğun sürdürülmesi

Derleme sistemi, en son API dosyalarını derleme sırasında oluşturulan API dosyalarıyla karşılaştırarak API'lerin geriye dönük uyumluluğu sürdürüp sürdürmediğini kontrol eder. java_sdk_library prebuilt_apis tarafından sağlanan bilgileri kullanarak uyumluluk kontrolünü gerçekleştirir. java_sdk_library ile oluşturulan tüm kitaplıkların, prebuilt_apis içindeki api_dirs en son sürümünde API dosyalarına sahip olması gerekir. Sürümü yayınladığınızda, API liste dosyaları ve taslak kitaplıkları PRODUCT=sdk_phone_armv7-sdk ile dist build ile elde edilebilir.

api_dirs özelliği, prebuilt_apis içindeki API sürüm dizinlerinin listesidir. API sürümü dizinleri Android.bp dizin düzeyinde bulunmalıdır.

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

Dizinleri, önceden oluşturulmuş dizin altındaki version / scope /api/ yapısıyla yapılandırın. version API düzeyine karşılık gelir ve scope dizinin genel, sistem veya test olup olmadığını tanımlar.

  • version / scope Java kitaplıklarını içerir.
  • version / scope /api API .txt dosyalarını içerir. Burada module_name .txt ve module_name -removed.txt adlı boş metin dosyalarını oluşturun.
     ├── 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