A plataforma Android contém um grande número de bibliotecas Java compartilhadas,
que podem ser incluídas no caminho de classe dos apps com a tag
<uses-library>
no manifesto do app. Os apps estão
vinculados a essas bibliotecas. Portanto, elas precisam ser tratadas como o restante da API
do Android em termos de compatibilidade, revisão e suporte a ferramentas. No entanto,
a maioria das bibliotecas não têm esses recursos.
O tipo de módulo java_sdk_library
ajuda a gerenciar bibliotecas
desse tipo. Os fabricantes de dispositivos podem usar esse mecanismo nas próprias
bibliotecas Java compartilhadas para manter a compatibilidade com versões anteriores das APIs deles.
Se os fabricantes de dispositivos usam as próprias bibliotecas com a
tag <uses-library>
no lugar do caminho bootclass,
a java_sdk_library
pode verificar se essas bibliotecas Java funcionam de forma
estável com a API.
A java_sdk_library
implementa APIs opcionais do SDK para os apps
usarem. As bibliotecas implementadas pela java_sdk_library
no seu
arquivo de build (Android.bp
) realizam estas operações:
- As bibliotecas de stubs são geradas para incluir
stubs
,stubs.system
estubs.test
. Essas bibliotecas de stubs são criadas com o reconhecimento das anotações@hide
,@SystemApi
e@TestApi
. - A
java_sdk_library
gerencia os arquivos de especificação da API (comocurrent.txt
) em um subdiretório da API. Esses arquivos são comparados com o código mais recente para garantir que estão nas versões mais atuais. Caso não estejam, você vai receber uma mensagem de erro explicando como atualizar. Analise todas as mudanças de atualização manualmente para garantir que elas atendam às suas expectativas.
Para atualizar todas as APIs, usem update-api
. Para verificar se uma API está atualizada, usem checkapi
. - Os arquivos de especificação da API são verificados em relação às versões
do Android publicadas mais recentes para garantir que a API seja compatível
com versões anteriores. Os módulos
java_sdk_library
fornecidos como parte do AOSP colocam as versões de lançamentos anteriores emprebuilts/sdk/<latest number>
. - Com relação às verificações de arquivos de especificação de API, é possível executar uma das três ações abaixo:
- Permitir que as verificações continuem (não fazer nada).
- Desativar as verificações adicionando o código abaixo à
java_sdk_library
:
unsafe_ignore_missing_latest_api: true,
- Fornecer APIs vazias para os novos módulos
java_sdk_library
criando arquivos de texto vazios com o nomemodule_name.txt
no diretórioversion/scope/api
. - Após a instalação da biblioteca de implementação de execução, um arquivo XML é gerado e instalado.
Como a java_sdk_library funciona
Uma java_sdk_library
conhecida como X
cria o seguinte:
- Duas cópias da biblioteca de implementação: uma com o nome
X
e outra com o nomeX.impl
. A bibliotecaX
vai ser instalada no dispositivo. A bibliotecaX.impl
vai estar disponível apenas se o acesso explícito à biblioteca de implementação for necessário para outros módulos, como para uso em testes. O acesso explícito quase nunca é necessário. - Os escopos podem ser ativados e desativados para personalizar o acesso. Assim como os modificadores de acesso de palavras-chave Java, um escopo público oferece uma ampla variedade de acessos, enquanto um escopo de teste contém apenas APIs usadas em testes. Para cada escopo ativado, a biblioteca cria:
- Um módulo de origem de stubs (do tipo de módulo
droidstubs
) consome a fonte da implementação e gera um conjunto de origens stub com o arquivo de especificação da API. - Uma biblioteca de stubs (do tipo de módulo
java_library
) é a versão compilada dos stubs As bibliotecas usadas para compilar não são iguais às fornecidas àjava_sdk_library
, o que garante que os detalhes da implementação não sejam vazados para os stubs da API. - Se você precisar de mais bibliotecas para compilar stubs, use as propriedades
stub_only_libs
estub_only_static_libs
para fornecê-las.
Se uma java_sdk_library
tem o nome "X
" e está sendo
compilada como "X
", não se esqueça de sempre se referir a ela dessa forma e não faça nenhuma
modificação no nome. O build vai selecionar uma biblioteca adequada. Para garantir que você está usando a
biblioteca mais adequada, inspecione seus stubs para saber se o build apresentou
erros. Faça as correções necessárias seguindo estas orientações:
- É possível verificar se você tem uma biblioteca adequada ao observar a linha de comando e inspecionar quais stubs estão listados para determinar o escopo:
- O escopo é grande demais: a biblioteca dependente precisa de um determinado escopo de APIs. No entanto, algumas APIs incluídas na biblioteca estão fora desse escopo, como as APIs do sistema incluídas nas APIs públicas.
- O escopo é muito restrito: 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 recebe a API pública. Isso geralmente resulta em um erro de compilação porque as APIs necessárias estão ausentes.
- Para trocar a biblioteca, siga um dos métodos abaixo:
- Mude a
sdk_version
para a versão que você precisa. OU - Especifique a biblioteca correta de forma explícita, por exemplo,
<X>.stubs
ou<X>.stubs.system
.
Como usar a java_sdk_library X
A biblioteca de implementação X
é usada quando é referenciada em
apex.java_libs
. No entanto, devido a uma limitação do Soong, quando a biblioteca
X
é referenciada em outro módulo java_sdk_library
dentro da mesma biblioteca APEX, a X.impl
precisa ser usada de forma explícita,
e não a biblioteca X
.
Uma biblioteca de stubs é usada quando a java_sdk_library
é referenciada
em outro lugar. Essa biblioteca é selecionada de acordo com a configuração
da propriedade sdk_version
do módulo dependente. Por exemplo, um módulo que
especifica sdk_version: "current"
usa os stubs públicos, enquanto um
módulo que especifica sdk_version: "system_current"
usa os
stubs do sistema. Se não é possível encontrar uma correspondência exata, a biblioteca de stubs mais próxima será
usada. Uma java_sdk_library
que oferecer apenas uma API pública vai
fornecer os stubs públicos para todos.
Exemplos e origens
As propriedades srcs
e api_packages
precisam
estar presentes na java_sdk_library
.
java_sdk_library { name: "com.android.future.usb.accessory", srcs: ["src/**/*.java"], api_packages: ["com.android.future.usb"], }
O AOSP recomenda (mas não exige) que as novas instâncias da java_sdk_library
ativem os escopos da API que eles querem usar de forma explícita. Também é possível
migrar (opcional) as instâncias java_sdk_library
atuais para
ativar os escopos da API que serão usados:
java_sdk_library { name: "lib", public: { enabled: true, }, system: { enabled: true, }, … }
Para configurar a biblioteca impl
usada na execução, use todas
as propriedades java_library
normais, 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, }
Use as propriedades abaixo para configurar bibliotecas de stubs:
merge_annotations_dirs
emerge_inclusion_annotations_dirs
.api_srcs
: a lista de arquivos de origem opcionais que fazem parte da API, mas não da biblioteca de execução.stubs_only_libs
: a lista das bibliotecas Java que estão no caminho de classe durante a criação de stubs.hidden_api_packages
: a lista de nomes de pacotes que precisam estar ocultos para a API.droiddoc_options
: argumento extra para a metalava.droiddoc_option_files
: lista os arquivos que podem ser referenciados dentro dasdroiddoc_options
usando$(location <label>)
, em que<file>
é uma entrada na lista.annotations_enabled
:
A java_sdk_library
é uma java_library
, mas não é um
módulo droidstubs
. Ela não oferece suporte a todas as propriedades
droidstubs
. O exemplo abaixo foi retirado do
arquivo de
build de biblioteca 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, }
Manter compatibilidade com versões anteriores
O sistema de build confirma se as APIs mantiveram a compatibilidade com versões anteriores
comparando os arquivos de API mais recentes com os arquivos de API
gerados durante o tempo de build. A java_sdk_library
executa essa
verificação de compatibilidade usando as informações fornecidas pelas prebuilt_apis
.
Os arquivos de API de todas as bibliotecas criadas com a java_sdk_library
precisam estar atualizados com
a versão mais recente de api_dirs
nas prebuilt_apis
.
Após lançar a versão, você poderá acessar os arquivos das listas de API e bibliotecas de stubs
com um build dist usando PRODUCT=sdk_phone_armv7-sdk
.
A propriedade api_dirs
é uma lista de diretórios de versão da API
nas prebuilt_apis
. Os diretórios de versão da API precisam estar
localizados no nível do diretório Android.bp
.
prebuilt_apis { name: "foo", api_dirs: [ "1", "2", .... "30", "current", ], }
Configure os diretórios com a estrutura version/scope/api/
no diretório de pré-builds. version
corresponde ao nível da API, e scope
define
se o diretório é público, do sistema ou de teste.
version/scope
contém bibliotecas Java.version/scope/api
contém arquivos.txt
da API. Nesse diretório, crie arquivos de texto vazios com os nomesmodule_name.txt
emodule_name-removed.txt
.├── 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