Java SDK kitaplığını uygulama

Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.

Android platformu, uygulama manifest dosyasında <uses-library> etiketi bulunan uygulamaların sınıf yoluna isteğe bağlı olarak 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 bu kitaplıkları Android API'nin geri kalanı gibi ele alın. Ancak çoğu kitaplıkta bu özelliklerin bulunmadığını unutmayın.

java_sdk_library modülü türü, bu tür kitaplıkları yönetmenize yardımcı olur. Cihaz üreticileri, API'lerinin geriye dönük uyumluluğunu korumak için kendi paylaşılan Java kitaplıkları için bu mekanizmayı kullanabilir. Cihaz üreticileri, bootclass 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 açısından kararlı olduğunu doğrulayabilir.

java_sdk_library, uygulamaların kullanabileceği 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:

• Stub kitaplıkları stubs, stubs.system ve stubs.test içerecek şekilde oluşturulur. Bu stubs kitaplıkları, @hide, @SystemApi ve @TestApi ek açıklamaları tanınarak oluşturulur.
• java_sdk_library, API alt dizinindeki API spesifikasyon 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ılır. Aksi takdirde, bunların nasıl güncelleneceğini açıklayan bir hata mesajı alırsınız. Beklentilerinizi karşıladığı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'u kullanın. Bir API'nin güncel olduğunu doğrulamak için m checkapi'ü kullanın.
• API'nin önceki sürümlerle geriye dönük uyumlu olmasını sağlamak için API spesifikasyon dosyaları en son yayınlanan Android sürümleriyle karşılaştırılır. AOSP kapsamında sağlanan java_sdk_library modülleri, daha önce yayınlanan sürümlerini prebuilts/sdk/<latest number>'a yerleştirir.
• API spesifikasyonu dosya kontrolleri ile ilgili olarak aşağıdaki üç seçenekten birini yapabilirsiniz:
• Kontrollerin devam etmesine izin verin. (Hiçbir şey yapmayın.)
• java_sdk_library dosyasına 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ığı yüklüyse 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ı başka bir kitaplık. X kitaplığı cihaza yüklüyse X.impl kitaplığı yalnızca diğer modüllerin uygulama kitaplığına açık erişim gerektirmesi durumunda (ör. testte kullanılması için) bulunur. Açık erişim iznine nadiren ihtiyaç duyulur.
2. Erişimi özelleştirmek için kapsamlar etkinleştirilebilir veya devre dışı bırakılabilir. (Java anahtar kelime erişim değiştiricilerine benzer şekilde, herkese açık kapsam geniş bir erişim yelpazesi sağlar; test kapsamı yalnızca testte kullanılan API'leri içerir.) Kitaplık, etkinleştirilen her kapsam için şunları oluşturur:
• Bir stubs kaynak modülü (droidstubs modülü türü): Uygulama kaynağını tüketir ve API spesifikasyonu dosyasıyla birlikte bir dizi stub kaynağı çıkışı verir.
• Stub kitaplığı (java_library modülü türü): Stub'ların derlenmiş sürümüdür. Bu derleme işleminde kullanılan kitaplıklar, java_sdk_library'e sağlananlarla aynı değildir. Bu sayede uygulama ayrıntıları API taslaklarına sızmaz.
• Stub'ları derlemek için ek kitaplıklara ihtiyacınız varsa bunları sağlamak üzere 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 her zaman bu şekilde atıfta bulunun ve değiştirmeyin. Derleme işleminde uygun bir kitaplık seçilir. En uygun kitaplığa sahip olduğunuzdan emin olmak için derlemenin hata oluşturup oluşturmadığını görmek üzere yapı taslaklarını inceleyin. Bu kılavuzu kullanarak gerekli düzeltmeleri yapın:

• Komut satırına bakarak ve kapsamınızı belirlemek için orada listelenen hangi stub'ların olduğunu inceleyerek uygun bir kitaplığınız olduğunu doğrulayın:
• Kapsam çok geniş: Bağımlı kitaplığın belirli bir API kapsamına ihtiyacı vardır. Ancak kitaplığa dahil edilen ve bu kapsamın dışında kalan API'ler (ör. herkese açık API'lere dahil edilen sistem API'leri) görürsünüz.
• Kapsam çok dar: Bağımlı kitaplığın tüm gerekli kitaplıklara erişimi yok. Örneğin, bağımlı kitaplığın sistem API'sini kullanması gerekir ancak bunun yerine herkese açık API'yi alır. Bu durum, gerekli API'ler eksik olduğu için genellikle 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
• Uygun kitaplığı (ör. <X>.stubs veya <X>.stubs.system) açıkça belirtin.

java_sdk_library X kullanımı

X uygulama kitaplığı, apex.java_libs'ten referans verildiğinde 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 referans verildiğinde X kitaplığı değil, X.impl kitaplığı açıkça kullanılmalıdır.

java_sdk_library başka bir yerden referans verildiğinde bir stubs kitaplığı kullanılır. Stub kitaplığı, bağlı modülün sdk_version mülk ayarına göre seçilir. Örneğin, sdk_version: "current" değerini belirten bir modül herkese açık stub'ları kullanırken sdk_version: "system_current" değerini belirten bir modül sistem stub'larını kullanır. Tam eşleşme bulunamazsa en yakın stub kitaplığı kullanılır. Yalnızca herkese açık API sağlayan bir java_sdk_library, herkese açık stub'ları sağlar.

Örnekler ve kaynaklar

srcs ve api_packages özellikleri java_sdk_library'da 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 tutmaz). Ayrıca, kullanacakları API kapsamlarını açıkça etkinleştirmek için (isteğe bağlı olarak) mevcut java_sdk_library örneklerini taşıyabilirsiniz:

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

Çalışma zamanında 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,
    }

Stub 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ındaki kitaplığın parçası olmayan isteğe bağlı kaynak dosyaların listesi.
• stubs_only_libs: Stub'ları oluştururken sınıf yolu içinde 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 bağımsız değişken.
• droiddoc_option_files: droiddoc_options içinden $(location <label>) kullanılarak referans verilebilen dosyaları listeler. <file>, listedeki bir giriştir.
• annotations_enabled.

java_sdk_library bir java_library'dur ancak droidstubs modülü değildir. Bu nedenle droidstubs özelliklerinin tümünü desteklemez. Aşağıdaki örnek, android.test.mock library build 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 sırasında oluşturulan API dosyalarıyla karşılaştırarak API'lerin geriye dönük uyumluluğunu 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ıklarda, prebuilt_apis'deki api_dirs'un en son sürümünde API dosyalarının bulunması gerekir. Sürümünüzü yayınladığınızda API, dosyaları listeler ve PRODUCT=sdk_phone_armv7-sdk ile dağıtım derlemesi yapılarak kitaplık taslakları elde edilebilir.

api_dirs mülkü, prebuilt_apis içindeki API sürümü dizinlerinin listesidir. API sürümü dizinleri Android.bp dizin düzeyinde olmalıdır.

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

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

• version/scope Java kitaplıkları içeriyor.
• version/scope/api, API .txt dosyalarını içerir. Burada 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