O driver C++ usa o guia de Último Grito 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.
Per 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 pela propriedade de destino CXX_VISIBILITY_PRESET. 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 pela propriedade de destino VISIbility_INLINES_HIDden.
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 | Sim | Sim |
Atualizar uma redeclaração de | Maybe [1] | Sim |
Remover um sÃmbolo | No | Maybe [2] |
Remover um sÃmbolo | Maybe [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) A stable ABI symbol could be removed from the public API (e.g. via documentation or removal from public headers) while still providing an exported symbol definition for backward compatibility. This is probably unlikely to happen, but if it does, it would be a rare case where the source and binary incompatible changes can be split into separate releases. |
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.