Controle de Versão ABI
Nesta página
O driver C++ usa o guia de Últimos Drepper para definir estabilidade, a convenção "soname" da biblioteca compartilhada Linux e a propriedade de destino CMake SOVERSION para controle de versão ABI.
Per Ulrich Drepper:
A definição de estabilidade deve, portanto, usar a interface documentada como base. Os usos legítimos de interfaces não devem ser afetados por alterações na implementação; usar interfaces de forma indefinida anula a garantia. O mesmo vale para o uso de símbolos internos completamente não documentados. Esses não devem ser usados de forma alguma.
De acordo com o Projeto de Documentação do Linux:
Cada biblioteca compartilhada tem um nome especial chamado `` soname''. O soname tem o prefixo ` ` lib'', o nome da biblioteca, a frase ` ` .so'', seguido por um ponto e um número de versão que é incrementado sempre que a interface é alterada (como exceção especial, as bibliotecas C de nível mais baixo não começam com ` ` lib''). Um soname totalmente qualificado inclui como prefixo o diretório em que está; em um sistema de trabalho, um soname totalmente qualificado é simplesmente um link simbólico para o 'nome real' da biblioteca compartilhada.*
De acordo com a documentação do CMake :
Para bibliotecas compartilhadas,
VERSIONeSOVERSIONpodem ser usados para especificar a versão de compilação e a versão da ABI, respectivamente. Ao construir ou instalar symlinks apropriados são criados se a plataforma suportar symlinks e o vinculador suportar so-names. Se apenas um de ambos for especificado, pressupõe-se que o ausente tenha o mesmo número de versão.*
Para fins de controle de versão da ABI , distinguimos entre a ABI estável e a ABI instável.
O número da versão da ABI é aumentado sempre que houver uma alteração incompatível com versões anteriores na ABI estável, conforme definido abaixo.
Importante
Somente a estabilidade da ABI estável é comunicada pelo número da versão da ABI. As alterações anteriores (in)compatíveis à ABI instável não são comunicadas pelo número de versão da ABI.
Observação
A política de controle de versão da ABI só é aplicável a bibliotecas compartilhadas. Não se aplica a bibliotecas estáticas.
Compatibilidade binária
Um namespace ABI é declarado dentro do namespace raiz da biblioteca (consulte Compatibilidade de origem), prefixado com a letra v e seguido por um número inteiro ou _noabi.
Exemplos de namespaces ABI incluem (em relação ao escopo de namespace global):
bsoncxx::v_noabibsoncxx::v1bsoncxx::v2bsoncxx::v99
Um namespace ABI instável é um namespace com o nome v_noabi. Qualquer outro namespace ABI é um namespace ABI estável. O namespace raiz não é um namespace ABI.
A ABI estável é o conjunto de símbolos exportados que são usados pela API pública e declarados em um namespace da ABI estável, com as seguintes exceções:
O símbolo ou as entidades de API públicas correspondentes são explicitamente documentados como experimentais ou ainda não preparados para a estabilidade da ABI.
A entidade não é declarada dentro de um namespace da ABI.
Incluindo essas exceções, todos os outros símbolos exportados são considerados parte da ABI instável.
Somente os símbolos cuja entidade API correspondente é explicitamente declarada com uma macro de exportação são exportados, conforme controlados pelo CXX_VISIbility_Preset propriedade de destino . Além disso, as entidades que são declaradas inline, explicitamente (por exemplo, com inline) ou implicitamente (por exemplo definições de função de membro em definições de classe , instanciações de modelo de variável/função etc.)não são exportadas, conforme controlado pelo VISIbility_INLINES_HIDden propriedade de destino .
Se houver um símbolo que deve ser exportado ou fazer parte da ABI estável, mas atualmente não é, envie um relatório de bug.
Importante
O uso direto de símbolos exportados que ignora a API pública não é permitido. Todos os símbolos exportados (estáveis ou instáveis) devem ser utilizados por meio da API pública. Se houver um símbolo que deve ser exportado ou fazer parte da ABI estável, mas atualmente não é, envie um relatório de bug.
Importante
Um símbolo só precisa ser usado pela API pública (mesmo indiretamente) para ser considerado parte da ABI estável. Um símbolo exportado que nunca foi usado por nenhuma entidade da API pública em nenhuma versão anterior não é considerado parte da ABI estável (consulte a nota acima).
Importante
O comportamento de um símbolo ABI estável também faz parte do ABI estável. Isso é para garantir um comportamento de tempo de execução consistente e compatível entre bibliotecas compartilhadas com o mesmo número de versão da ABI. O comportamento deve ser consistente com a documentação de uma ou mais entidades de API pública que usam o símbolo (mesmo que indiretamente) de modo que não haja mudança observável no comportamento da API pública (dentro do escopo do que é explicitamente documentado) em versões com a mesma ABI número da versão.
Observação
Algumas entidades que fazem parte da API pública podem não fazer parte da ABI estável (por exemplo funções in-line, variáveis in-line e instanciações de modelo de funções e variáveis). Por outro lado, algumas entidades que fazem parte da ABI estável podem não fazer parte da API pública (por exemplo, uma função de membro privado exportada). Consulte Controle de versão da API.
Construa a compatibilidade do sistema
A política estável da ABI sobre propriedades do sistema de construção é principalmente a mesma que a da API pública (consulte Compatibilidade do sistema de construção da API) com as seguintes diferenças:
Em vez de propriedades que afetam diretamente a API pública, as propriedades que afetam diretamente a ABI estável são consideradas parte da ABI estável.
O soname é considerado parte da ABI estável. Isso significa que, em contraste com a API pública, o
BSONCXX_OUTPUT_NAMEé considerado parte da ABI estável, pois afeta diretamente o soname da biblioteca compartilhada bsoncxx resultante.O "soname" não é aplicável no Windows. Consulte Bibliotecas compartilhadas (somente MSVC).
Observação
Apoiamos a estabilidade da stable API por configuração de compilação. Não aceitamos compatibilidade da stable API em diferentes configurações de compilação. Por exemplo, não se espera que uma biblioteca compartilhada gerada com BSONCXX_OUTPUT_NAME=bsoncxx seja compatível com um programa compilado com uma ABI estável produzida usando uma configuração de compilação com BSONCXX_OUTPUT_NAME=bsoncxx-custom-basename. (Isto é particularmente importante ao utilizar geradores de múltiplas configurações, como o Visual Studio):
Redeclarações do namespace raiz
O namespace raiz fornece "redeclarações" de entidades declaradas em um namespace ABI. O namespace da ABI pode diferir entre entidades que estão sendo redeclaradas.
Por exemplo, todas as seguintes redeclarações podem estar presentes simultaneamente:
bsoncxx::example::foo-->bsoncxx::v_noabi::example::foobsoncxx::example::bar-->bsoncxx::v1::example::barbsoncxx::example::baz-->bsoncxx::v2::example::baz
As redeclarações do namespace raiz são projetadas para permitir a adição de símbolos binários incompatíveis no vB sem quebrar a compatibilidade binária dos símbolos vA . Elas facilitam a depreciação de símbolos ABI estáveis e, ao mesmo tempo, oferecem a oportunidade para uma transição limpa de vA para vB sem quebrar a compatibilidade binária. Elas permitem que o código do usuário opte por "atualizações de redeclaração" que reduzem as alterações necessárias no código-fonte ao fazer a transição de vA para vB.
Essas atualizações de redeclaração destinam-se a apoiar uma transição limpa dos símbolos ABI obsoletos e a serem removidos entre as versões. Da mesma forma, os usuários são encorajados a usar as declarações de namespace raiz por padrão para optar por essas atualizações. No entanto, os usuários podem precisar usar qualificadores explícitos de namespace ABI ao fazer referência a entidades C++ Driver em seus próprios ABIs estáveis, dependendo de sua própria política de estabilidade.
A tabela de compatibilidade a seguir descreve quando o número da versão principal da API ou o número da versão da ABI deve ser aumentado devido a uma alteração incompatível:
Tipo de alteração | Fonte compatível | Compatível com Binários |
Adicionar um novo símbolo vB | Sim | Sim |
Atualizar uma redeclaração de vA para vB | Talvez [1] | Sim |
Remover um símbolo vA (da API pública) | No | Talvez [2] |
Remover um símbolo vA (da ABI estável) | Talvez [2] | No |
| [1] | Uma entidade vB pode ser 100% compatível com a API vA , apesar de exigir o uso de um novo símbolo ABI estável incompatível. |
| [2] | (1, 2) Um símbolo ABI estável pode ser removido da API pública (por exemplo, por meio de documentação ou remoção de cabeçalhos públicos) e ainda fornecer uma definição de símbolo exportado para compatibilidade com versões anteriores. É improvável que isso aconteça, mas, se acontecer, será um caso raro em que as alterações incompatíveis com a origem e o binário possam ser divisão em versões separadas. |
Importante
O número inteiro usado por um namespace ABI NÃO corresponde diretamente a um número de versão da ABI. O número da versão da ABI é aumentado sempre que ocorre qualquer alteração incompatível com binários, mesmo quando é a remoção de um único símbolo da ABI estável. Um aumento do número de versão da ABI de A para B NÃO implica a depreciação ou remoção de símbolos declarados no namespace da ABI vA (se houver).
Descontinuação e remoção
A política para depreciação e remoção de símbolos na ABI estável é a mesma da API pública. Para obter mais informações, consulte Descontinuação e remoção de API.
Uma versão contendo alterações binárias incompatíveis aumentará o número da versão da ABI em vez do número da versão principal da API. No entanto, é provável que, quando o número da versão da ABI seja aumentado, o número da versão principal da API também seja aumentado, pois uma alteração incompatível binária provavelmente também será uma alteração incompatível com a fonte.