Implementa la libreria SDK Java

La piattaforma Android contiene un numero elevato di librerie Java condivise che può essere incluso facoltativamente nel classpath delle app con Tag <uses-library> nel file manifest dell'app. Link delle app rispetto a queste librerie, quindi trattale come il resto dell'API Android in termini di compatibilità, revisione delle API e supporto degli strumenti. Tuttavia, tieni presente che la maggior parte delle librerie non dispone di queste funzionalità.

Il tipo di modulo java_sdk_library consente di gestire le librerie di questo tipo. I produttori di dispositivi possono utilizzare questo meccanismo per i propri dispositivi librerie Java condivise per mantenere la compatibilità con le versioni precedenti delle API. Se i produttori di dispositivi utilizzano le proprie librerie Java condivise tramite <uses-library> anziché il percorso bootclass, java_sdk_library può verificare che le librerie Java siano stabile all'API.

L'java_sdk_library implementa le API SDK facoltative per l'utilizzo app. Librerie implementate tramite java_sdk_library in del file di build (Android.bp) esegui queste operazioni:

• Le librerie stub vengono generate per includere stubs, stubs.system e stubs.test. Questi Le librerie stub vengono create riconoscendo @hide, Annotazioni @SystemApi e @TestApi.
• java_sdk_library gestisce i file delle specifiche delle API (ad esempio current.txt) in una sottodirectory dell'API. Questi file vengono confrontati con il codice più recente per garantire che siano versioni correnti. In caso contrario, riceverai un messaggio di errore che indica che spiega come aggiornarli. Esamina manualmente tutte le modifiche di aggiornamento a assicurarti che soddisfino le tue aspettative.
  
  Per aggiornare tutte le API, utilizza m update-api. Per verificare che un'API sia aggiornata: usa m checkapi.
• I file delle specifiche dell'API vengono confrontati con i file più recenti versioni di Android pubblicate per garantire che l'API sia compatibile con le versioni precedenti con le versioni precedenti. I moduli java_sdk_library forniti come parte di AOSP, le loro versioni rilasciate in precedenza prebuilts/sdk/<latest number>.
• Per quanto riguarda i controlli sui file delle specifiche API, puoi: uno dei tre elementi seguenti:
• Consenti i controlli per procedere. Non fare nulla.
• Disattiva i controlli aggiungendo a java_sdk_library il seguente codice:
  unsafe_ignore_missing_latest_api: true,
• Fornisci API vuote per i nuovi moduli java_sdk_library creando file di testo vuoti denominati module_name.txt in nella directory version/scope/api.
• Se è installata la libreria di implementazione per il runtime, viene visualizzato un file XML vengono generati e installati.

Come funziona java_sdk_library

Un java_sdk_library denominato X crea quanto segue:

1. Due copie della libreria di implementazione: una libreria chiamata X e un'altra chiamata X.impl. La libreria X è installata sul dispositivo. La raccolta X.impl è disponibile solo con accesso esplicito a la libreria di implementazione è richiesta da altri moduli, ad esempio per l'uso test. Tieni presente che raramente è necessario un accesso esplicito.
2. Gli ambiti possono essere abilitati e disabilitati per personalizzare l'accesso. (Simile a Java modificatori di accesso alle parole chiave, un ambito pubblico offre un'ampia gamma di accessi, un l'ambito di test contiene API utilizzate solo nei test.) Per ogni ambito abilitato, crea quanto segue:
• Un modulo di origine stub (di tipo di modulo droidstubs) - consuma l'origine dell'implementazione e restituisce un insieme di origini stub il file delle specifiche dell'API.
• Una libreria stub (di tipo di modulo java_library); è il completamente compilata degli stub. Le librerie usate per la compilazione non sono uguali a quelle fornite a java_sdk_library, il che garantisce che i dettagli dell'implementazione non finiscano negli stub dell'API.
• Se hai bisogno di librerie aggiuntive per compilare gli stub, utilizza stub_only_libs e stub_only_static_libs proprietà per fornirli.

Se un java_sdk_library si chiama "X" ed è compilate come "X", fai sempre riferimento ad essa in questo modo e non modificare li annotino. La build selezionerà una libreria appropriata. Per assicurarti di avere libreria più appropriata, esamina gli stub per vedere se la build è stata introdotta errori. Apporta le correzioni necessarie utilizzando queste indicazioni:

• Verifica di avere una libreria appropriata esaminando la riga di comando e controllare quali stub sono elencati per determinare l'ambito:
• L'ambito è troppo ampio: la libreria dipendente richiede un determinato ambito di API. Ma vedi le API incluse nella libreria che non rientrano in questo ambito, come le API di sistema incluse con le API pubbliche.
• L'ambito è troppo limitato: la libreria che dipende non ha accesso a tutti i librerie richieste. Ad esempio, la libreria "dipendente" deve utilizzare di sistema, ma ottiene l'API pubblica. Questo di solito comporta errore di compilazione perché mancano le API necessarie.
• Per correggere la libreria, esegui solo una delle seguenti operazioni:
• Modifica sdk_version per selezionare la versione che ti serve. OPPURE
• Specifica in modo esplicito la libreria appropriata, ad esempio <X>.stubs o <X>.stubs.system.

Utilizzo di java_sdk_library X

La libreria di implementazione X viene utilizzata quando viene fatto riferimento da apex.java_libs. Tuttavia, a causa di una limitazione di Presto, quando Viene fatto riferimento a X in un altro modulo java_sdk_library nella stessa libreria APEX, X.impl in modo esplicito deve essere utilizzato, non la libreria X.

Quando si fa riferimento a java_sdk_library altrove, uno stub libreria in uso. La libreria stub viene selezionata in base dell'impostazione della proprietà sdk_version del modulo. Ad esempio, un modulo specifica che sdk_version: "current" utilizza gli stub pubblici, mentre una che specifica sdk_version: "system_current" utilizza stub di sistema. Se non è possibile trovare una corrispondenza esatta, la libreria stub più vicina viene in uso. Un java_sdk_library che fornisce solo un'API pubblica che fornisca a tutti gli stub pubblici.

Figura 1. Flusso di creazione con la libreria SDK Java

.

Esempi e fonti

Le proprietà srcs e api_packages devono sarà presente nel java_sdk_library.

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

AOSP consiglia (ma non richiede) il nuovo java_sdk_library le istanze VM abilitano esplicitamente gli ambiti API che vogliono utilizzare. Puoi anche (facoltativamente) eseguire la migrazione di istanze java_sdk_library esistenti a attivare esplicitamente gli ambiti API che utilizzeranno:

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

Per configurare la libreria impl utilizzata per il runtime, usa tutte le normali proprietà java_library, come hostdex, compile_dex e 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,
    }

Per configurare le librerie stub, utilizza le seguenti proprietà:

• merge_annotations_dirs e merge_inclusion_annotations_dirs.
• api_srcs: l'elenco di file di origine facoltativi che fanno parte dell'API, ma non fa parte della libreria di runtime.
• stubs_only_libs: l'elenco delle librerie Java che si trovano nel classpath durante la creazione di stub.
• hidden_api_packages: l'elenco di nomi dei pacchetti che devono essere nascosti dall'API.
• droiddoc_options: argomento aggiuntivo per metalava.
• droiddoc_option_files: elenca i file a cui è possibile fare riferimento in droiddoc_options utilizzando $(location <label>), dove <file> è una voce dell'elenco.
• annotations_enabled.

java_sdk_library è un java_library, ma non è un droidstubs e quindi non supporta tutti i droidstubs proprietà. L'esempio seguente è stato tratto dalla Creazione della libreria 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,
    }

Mantenere la compatibilità con le versioni precedenti

Il sistema di compilazione verifica se le API sono state mantenute a ritroso la compatibilità confrontando i file API più recenti con i API al momento della creazione. java_sdk_library esegue controllo di compatibilità utilizzando le informazioni fornite da prebuilt_apis. Tutte le librerie create con java_sdk_library devono avere file API nell'ultima versione di api_dirs in prebuilt_apis. Quando rilasci la versione, l'API elenca i file e gli stub puoi ottenere le librerie con dist build con PRODUCT=sdk_phone_armv7-sdk.

La proprietà api_dirs è un elenco di directory delle versioni dell'API nel mese di prebuilt_apis. Le directory della versione API devono essere situato al livello della directory Android.bp.

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

Configura le directory con version/scope/api/ nella directory predefinita. version corrisponde al livello API e scope definisce se la directory è pubblica, di sistema o di test.

• version/scope contiene librerie Java.
• version/scope/api contiene API .txt file. Crea file di testo vuoti denominati module_name.txt e module_name-removed.txt qui.

   ├── 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