O Google tem o compromisso de promover a igualdade racial para as comunidades negras. Saiba como.

Implementando Biblioteca Java SDK

A plataforma Android contém um grande número de bibliotecas Java compartilhados que pode, opcionalmente, ser incluídos no classpath de aplicativos com o <uses-library> tag no manifesto do aplicativo. Os aplicativos são vinculados a essas bibliotecas, portanto, trate-os como o restante da API do Android em termos de compatibilidade, revisão de API e suporte a ferramentas. Observe, entretanto, que a maioria das bibliotecas não possui esses recursos.

O java_sdk_library tipo de módulo ajuda a gerenciar bibliotecas deste tipo. Os fabricantes de dispositivos podem usar esse mecanismo para suas próprias bibliotecas Java compartilhadas, para manter a compatibilidade com versões anteriores de suas APIs. Se os fabricantes de dispositivos usam suas próprias bibliotecas Java compartilhados através do <uses-library> tag em vez do caminho bootclass, java_sdk_library pode verificar que as bibliotecas Java são API estável.

Os java_sdk_library implementos opcionais APIs do SDK para uso por aplicativos. Bibliotecas implementadas através java_sdk_library em seu arquivo de construção ( Android.bp ) realizar as seguintes operações:

  • As bibliotecas topos são geradas para incluir stubs , stubs.system , e stubs.test . Esses stubs bibliotecas são criados por reconhecer @hide , @SystemApi e @TestApi anotações.
  • O java_sdk_library gerencia arquivos de especificação API (como current.txt ) em um subdiretório API. Esses arquivos são verificados em relação ao código mais recente para garantir que sejam as versões mais recentes. Se não forem, você receberá uma mensagem de erro que explica como atualizá-los. Revise manualmente todas as alterações de atualização para garantir que correspondam às suas expectativas.
  • Os arquivos de especificação da API são verificados em relação às versões do Android publicadas mais recentemente para garantir que a API seja compatível com versões anteriores. Os java_sdk_library módulos fornecidos como parte do AOSP lugar suas versões lançadas anteriormente em prebuilts/sdk/<latest number> .
  • Com relação à especificação API arquivos cheques, você pode fazer uma das três coisas seguintes:
    • Permita que as verificações continuem. (Não faça nada.)
    • Cheques desativar adicionando o seguinte para java_sdk_library :
      unsafe_ignore_missing_latest_api: true,
    • Fornecer APIs vazios para novas java_sdk_library módulos através da criação de arquivos de texto vazio chamado module_name.txt no version/scope/api diretório .
  • Se a biblioteca de implementação para o tempo de execução estiver instalada, um arquivo XML será gerado e instalado.

Como funciona o java_sdk_library

A java_sdk_library chamado X cria o seguinte:

  1. Duas cópias da biblioteca de implementação: uma biblioteca chamada X e outro chamado X.impl . Biblioteca X está instalado no dispositivo. Biblioteca X.impl existe apenas se o acesso explícito à biblioteca implementação é necessária por outros módulos, como para uso em testes. Observe que o acesso explícito raramente é necessário.
  2. Os escopos podem ser ativados e desativados para personalizar o acesso. (Semelhante aos modificadores de acesso por palavra-chave Java, um escopo público fornece uma ampla gama de acesso; um escopo de teste contém APIs usadas apenas em testes.) Para cada escopo habilitado, a biblioteca cria o seguinte:
    • A topos módulo de origem (de droidstubs tipo de módulo) - consome a fonte implementação e gera um conjunto de fontes de stub juntamente com o arquivo de especificação API.
    • A topos biblioteca (de java_library tipo de módulo) - é a versão compilada dos topos. Os libs usados para compilar este não são as mesmas que as fornecidas ao java_sdk_library , o que garante os detalhes de implementação não vazar para os topos de API.
    • Se você precisar de bibliotecas adicionais para compilar os stubs, use os stub_only_libs e stub_only_static_libs propriedades para fornecê-los.

Se um java_sdk_library é chamado de “ X ”, e está sendo compilado contra como “ X ”, sempre se referem a ele dessa forma e não modificá-lo. A construção selecionará uma biblioteca apropriada. Para garantir que você tenha a biblioteca mais apropriada, inspecione seus stubs para ver se a construção introduziu erros. Faça as correções necessárias usando esta orientação:

  • Verifique se você tem uma biblioteca apropriada olhando a linha de comando e inspecionando quais stubs estão listados lá para determinar seu escopo:
    • O escopo é muito amplo: a biblioteca dependente precisa de um certo escopo de APIs. Mas você vê APIs incluídas na biblioteca que estão fora desse escopo, como APIs de sistema incluídas nas APIs públicas.
    • O escopo é muito estreito: a biblioteca dependente não tem acesso a todas as bibliotecas necessárias. Por exemplo, a biblioteca dependente precisa usar a API do sistema, mas obtém a API pública. Isso geralmente resulta em um erro de compilação porque as APIs necessárias estão ausentes.
  • Para corrigir a biblioteca, fazer apenas uma das seguintes opções:
    • Alterar o sdk_version para selecionar a versão que você precisa. OU
    • Explicitamente especificar a biblioteca apropriada, tal como <X>.stubs ou <X>.stubs.system .

uso de java_sdk_library X

A biblioteca implementação X é usado quando é referenciado a partir apex.java_libs . No entanto, devido a uma limitação Soong, quando a biblioteca X é referenciado a partir de outro java_sdk_library módulo dentro da mesma biblioteca APEX, X.impl explicitamente deve ser usado, não biblioteca X .

Quando o java_sdk_library é referenciada de outros lugares, uma biblioteca tocos é usado. A biblioteca tocos é selecionado de acordo com o módulo dependendo sdk_version definição da propriedade. Por exemplo, um módulo que especifica sdk_version: "current" usa o stubs públicos, enquanto que um módulo que especifica sdk_version: "system_current" usa os topos do sistema. Se uma correspondência exata não puder ser encontrada, a biblioteca stub mais próxima será usada. A java_sdk_library que apenas fornece uma API pública irá fornecer os topos públicas para todos.

Fluxo de construção com biblioteca Java SDK
Figura 1. Fluxo Construir com biblioteca Java SDK

Exemplos e fontes

Os srcs e api_packages propriedades devem estar presentes no java_sdk_library .

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

AOSP recomenda (mas não exige) que os novos java_sdk_library casos permitir explicitamente a API escopos eles querem usar. Você pode também (opcionalmente) migrar existente java_sdk_library instâncias para permitir explicitamente a API escopos eles vão usar:

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

Para configurar o impl biblioteca usada para tempo de execução, use todas as normais java_library propriedades, como 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,
    }

Para configurar bibliotecas de stubs, use as seguintes propriedades:

  • merge_annotations_dirs e merge_inclusion_annotations_dirs .
  • api_srcs : A lista de arquivos de origem opcionais que fazem parte da API mas não faz parte da biblioteca de tempo de execução.
  • stubs_only_libs : A lista de bibliotecas Java que estão no classpath quando a construção de topos.
  • hidden_api_packages : A lista de nomes de pacotes que devem ser escondidos do API.
  • droiddoc_options : argumento adicional para metalava .
  • droiddoc_option_files : lista os arquivos que podem ser referenciados a partir de dentro droiddoc_options usando $(location <label>) , onde <file> é uma entrada na lista.
  • annotations_enabled .

O java_sdk_library é um java_library , mas não é um droidstubs módulo e assim não suporta todos os droidstubs propriedades. O exemplo a seguir foi retirado da construção biblioteca android.test.mock arquivo.

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

Manter compatibilidade com versões anteriores

O sistema de construção verifica se as APIs mantiveram a compatibilidade com versões anteriores, comparando os arquivos de API mais recentes com os arquivos de API gerados no momento da construção. Os java_sdk_library executa a verificação de compatibilidade usando as informações fornecidas pelo prebuilt_apis . Todas as bibliotecas construídas com java_sdk_library deve ter arquivos de API na versão mais recente do api_dirs em prebuilt_apis . Quando você lançar a versão, os arquivos de listas de API e bibliotecas stubs pode ser obtida com a construção dist com PRODUCT=sdk_phone_armv7-sdk .

O api_dirs propriedade é lista de diretórios de versão API em prebuilt_apis . Os diretórios API da versão deve ser localizado no Android.bp nível de diretório.

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

Configure os diretórios com a version / scope /api/ estrutura sob o diretório prebuilts. version corresponde ao nível API e scope define se o diretório é pública, sistema ou teste.

  • version / scope contém bibliotecas Java.
  • version / scope /api contém API .txt arquivos. Criar arquivos de texto vazio chamado module_name .txt e module_name -removed.txt aqui.
     ├── 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