Java SDK Kitaplığını Uygulama

Android platformu, isteğe bağlı olarak uygulama bildiriminde <uses-library> etiketiyle uygulamaların sınıf yoluna dahil edilebilecek çok sayıda paylaşılan Java kitaplığı içerir. Uygulamalar bu kitaplıklara bağlanır, bu nedenle uyumluluk, API incelemesi ve araç desteği açısından onlara Android API'nin geri kalanı gibi davranın. Ancak, çoğu kitaplığın 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'leri için geriye dönük uyumluluğu korumak için bu mekanizmayı kendi paylaşılan Java kitaplıkları için kullanabilir. Aygıt üreticileri, önyükleme sınıfı yolu yerine <uses-library> etiketi aracılığıyla kendi paylaşılan Java kitaplıklarını kullanıyorsa, java_sdk_library , bu Java kitaplıklarının API 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:

  • Stubs kitaplıkları stubs , stubs.system ve stubs.test içerecek şekilde oluşturulur. Bu taslak kitaplıkları @hide , @SystemApi ve @TestApi ek açıklamaları tanınarak 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ümler olduklarından emin olmak için en son koda göre kontrol edilir. Değillerse, bunların nasıl güncelleneceğini açıklayan bir hata mesajı alırsınız. Beklentilerinizle eşleştiğinden 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 uyumlu olduğundan emin olmak için en son yayınlanan Android sürümlerine göre kontrol edilir. AOSP'nin bir parçası olarak sağlanan java_sdk_library modülleri, önceden yayımlanmış sürümlerini prebuilts prebuilts/sdk/<latest number> içine yerleştirir.
  • API spesifikasyon dosyaları kontrolleriyle ilgili olarak, aşağıdaki üç şeyden birini yapabilirsiniz:
    • Kontrollerin devam etmesine izin verin. (Hiçbir şey yapmayın.)
    • java_sdk_library aşağıdakileri 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ı için uygulama kitaplığı kuruluysa, bir XML dosyası oluşturulur ve kurulur.

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 kitaplık. Kitaplık X , cihaza yüklenir. Kitaplık X.impl , yalnızca, testte kullanım gibi diğer modüller tarafından uygulama kitaplığına açık erişim gerektiğinde oradadır. Açık erişime nadiren ihtiyaç duyulduğunu unutmayın.
  2. Erişimi özelleştirmek için kapsamlar etkinleştirilebilir ve devre dışı bırakılabilir. (Java anahtar sözcük erişim değiştiricilerine benzer şekilde, genel bir kapsam geniş bir erişim aralığı sağlar; bir 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 türünden) - uygulama kaynağını tüketir ve API belirtim dosyasıyla birlikte bir dizi saplama kaynağının çıktısını verir.
    • Bir taslak kitaplığı ( java_library modül tipinde) - taslakların derlenmiş versiyonudur. Bunu derlemek için kullanılan java_sdk_library , java_sdk_library için sağlananlarla aynı değildir, bu da 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 başvurun ve onu değiştirmeyin. Derleme uygun bir kitaplık seçecektir. En uygun kitaplığa sahip olduğunuzdan emin olmak için, derlemenin hatalara yol açıp açmadığını görmek için taslaklarınızı inceleyin. Bu kılavuzu kullanarak gerekli düzeltmeleri yapın:

  • Kapsamınızı belirlemek için komut satırına bakarak ve orada hangi saplamaların listelendiğini inceleyerek uygun bir kitaplığa sahip olduğunuzu doğrulayın:
    • Kapsam çok geniş: Bağımlı kitaplığın belirli bir API kapsamına ihtiyacı var. Ancak, genel API'lere dahil edilen sistem API'leri gibi, kitaplığa dahil edilen ve bu kapsamın dışında kalan API'ler görürsünüz.
    • Kapsam çok dar: Bağlı kitaplığın gerekli kitaplıkların tümüne erişimi yok. Örneğin, bağımlı kitaplığın sistem API'sini kullanması gerekir, ancak bunun yerine genel API'yi alır. Bu genellikle gerekli API'ler eksik olduğundan bir 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ğiştirin. VEYA
    • <X>.stubs veya <X>.stubs.system gibi uygun kitaplığı açıkça belirtin.

java_sdk_library X kullanımı

Uygulama kitaplığı X , apex.java_libs başvurulduğunda 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 referans alındığında, bir taslak kitaplığı kullanılır. Saplama 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" belirten bir modül sistem taslaklarını kullanır. Tam bir eşleşme bulunamazsa, en yakın saplama kitaplığı kullanılır. Yalnızca genel bir API sağlayan bir java_sdk_library , herkese açık taslakları sağlayacaktır.

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

Örnekler ve kaynaklar

srcs ve api_packages özellikleri java_sdk_library içinde bulunmalıdır .

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 zorunlu değildir). Ayrıca (isteğe bağlı olarak) kullanacakları API kapsamlarını açıkça etkinleştirmek için mevcut java_sdk_library örneklerini 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ştururken 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 girdidir.
  • annotations_enabled .

java_sdk_library bir java_library , ancak bir droidstubs modülü değildir ve bu nedenle tüm droidstubs özelliklerini desteklemez. Aşağıdaki örnek, android.test.mock kitaplığı 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ğu koruma

Derleme sistemi, en son API dosyalarını derleme zamanı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, api_dirs içindeki prebuilt_apis en son sürümünde API dosyalarına sahip olması gerekir. Sürümü yayınladığınızda, API, dosyaları listeler 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ş dizini altında version / scope /api/ yapısıyla yapılandırın. version , API düzeyine karşılık gelir ve scope , dizinin genel mi, sistem mi yoksa test mi olduğunu tanımlar.

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