Menu Docs
Página inicial do Docs
/
Idiomas
/
C++
/
Driver C++

Versão de API e ABI

Nesta página

  • Controle de Versão da API
  • Controle de Versão ABI
  • Estrutura do arquivo de cabeçalho
  • Nomes de arquivos da biblioteca
  • Bibliotecas compartilhadas
  • Bibliotecas compartilhadas (somente MSVC)
  • Bibliotecas estáticas
  • Bibliotecas estáticas (somente MSVC)

Por questões de brevidade, esta página pode descrever propriedades e recursos como se se aplicassem apenas à biblioteca bsoncxx. A menos que indicado de outra forma, pode-se presumir que as propriedades e recursos descritos sejam aplicáveis da mesma forma à biblioteca mongocxx.

Controle de Versão da API

Consultea seção Versões da API .

Controle de Versão ABI

Consulte Controle de versão da ABI.

Estrutura do arquivo de cabeçalho

Os arquivos de cabeçalho públicos da biblioteca bsoncxx são organizados pelo namespace ABI :

${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_INCLUDEDIR}/
└── bsoncxx/
   ├── v_noabi/bsoncxx/
   │   └── ...
   ├── v1/bsoncxx/
   │   └── ...
   ├── v2/bsoncxx/
   │   └── ...
   └── vN/bsoncxx/
      └── ...

Para compatibilidade direta, um arquivo de cabeçalho público em um diretório de namespace ABI vA pode incluir um arquivo de cabeçalho em um diretório de namespace ABI mais recente vB, onde A < B. Essa compatibilidade direta inclui diretivas, quando suportadas, será explicitamente documentada. Quando a estabilidade da ABI é necessária, recomendamos incluir cabeçalhos do mais recente diretório de namespace da ABI estável. Se a estabilidade da ABI não for necessária, recomendamos incluir o cabeçalho de ABI instável apropriado.

Importante

O diretório de namespace ABI instável bsoncxx/v_noabi/ é priorizado antes do diretório raiz bsoncxx/ em incluir caminhos, de modo que #include <bsoncxx/example.hpp> seja equivalente a #include <bsoncxx/v_noabi/bsoncxx/example.hpp>.

Observação

A estabilidade de uma diretiva de inclusão não documentada não é suportada.

Os arquivos do pacote são instalados em subdiretórios no ${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_LIBDIR}/. Os usuários são altamente encorajados a usar esses arquivos do pacote para obter o cabeçalho da biblioteca bsoncxx (bem como para vincular e definir sinalizadores de compilação). A configuração manual de caminhos de inclusão para obter arquivos de cabeçalho bsoncxx não é recomendada. Os arquivos do pacote são descritos mais abaixo.

Em todos os casos, os arquivos de configuração do pacote CMake são o método recomendado para importar bibliotecas de drivers C++ .

Nomes de arquivos da biblioteca

O nome do arquivo e a presença de links simbólicos dependem da plataforma e da cadeia de ferramentas usadas para construir a biblioteca, bem como do tipo de biblioteca (compartilhada versus estática).

Bibliotecas compartilhadas

Importante

As bibliotecas compartilhadas no Windows, quando configuradas com a cadeia de ferramentas MSVC no Windows, são tratadas de forma diferente devido a considerações especiais específicas do Windows. Consulte Bibliotecas compartilhadas (somente MSVC) abaixo.

O "nome real" das bibliotecas compartilhadas usa o seguinte padrão:

lib<basename>.so.<api-version-number>

onde:

  • <basename> corresponde à variável de configuração BSONCXX_OUTPUT_BASENAME CMake (MONGOCXX_OUTPUT_BASENAME para a biblioteca mongocxx). Por padrão, isso é definido como bsoncxx e mongocxx. O nome de base de uma biblioteca estática tem o sufixo -static.

  • <api-version-number> é a versão MAJOR, MINOR e PATCH para a configuração de compilação fornecida, correspondente à variável de configuração BUILD_VERSION do CMake. (Observação: definir explicitamente essa variável de configuração não deve ser necessário no uso regular do driver C++.)

  • As extensões de número da versão da API não estão incluídas no nome real (por exemplo, o -alpha em 1.2.3-alpha).

Exemplos de nomes reais de bibliotecas esperados incluem:

libbsoncxx.so.1.0.0
libbsoncxx.so.2.3.4

A propriedade de destino SOVERSION do CMake e o comportamento "namelink" são usados para também instalar links simbólicos para o diretório da biblioteca consistente com a convenção de soname do Linux. Esses links simbólicos incluem o número da versão da ABI como parte do soname da biblioteca.

Por exemplo, o seguinte diretório lib contém os arquivos de biblioteca esperados para uma biblioteca bsoncxx com API versão 1.2.3 e ABI versão 10, onde a -> b indica que a é um link simbólico para b:

${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_LIBDIR}/
├── libbsoncxx.so.1.2.3
├── libbsoncxx.so.10 -> libbsoncxx.so.1.2.3
├── libbsoncxx.so -> libbsoncxx.so.10
├── cmake/bsoncxx-1.2.3/
│   ├── bsoncxx-config.cmake
│   └── ...
└── pkgconfig/
   └── libbsoncxx.pc

O nome do pacote CMake para bibliotecas bsoncxx é controlado por BSONCXX_OUTPUT_BASENAME (MONGOCXX_OUTPUT_BASENAME para bibliotecas mongocxx). Eles devem ser importados de acordo com o procedimento de pesquisa do modo de configuração do CMake . Por exemplo, supondo que o driver C++ tenha sido instalado em um prefixo $INSTALLDIR:

# The CMake package may be imported via CMAKE_PREFIX_PATH (recommended)...
cmake -S example -B example-build -D CMAKE_PREFIX_PATH="$INSTALLDIR"
# Or via <PackageName>_ROOT (assuming BSONCXX_OUTPUT_NAME=bsoncxx)...
cmake -S example -B example-build -D bsoncxx_ROOT="$INSTALLDIR"
# Or via ``PATHS`` in the ``find_package()`` command... or etc.
# find_package(bsoncxx CONFIG REQUIRED PATHS "$INSTALLDIR")

Observação

O Driver C é uma dependência necessária para o Driver C++. Os arquivos de configuração do pacote CMake para o C Driver também podem precisar ser importados usando a mesma abordagem (ou semelhante) para satisfazer essa dependência.

Embora o driver C++ também forneça arquivos pkg-config, os usuários são altamente encorajados a usar arquivos de configuração do pacote CMake.

O nome do arquivo pkg-config para bibliotecas bsoncxx também é controlado por BSONCXX_OUTPUT_NAME e segue o padrão lib<basename>.pc. A variável de ambiente PKG_CONFIG_PATH pode precisar ser usada para aumentar o caminho do Atlas Search do pkg-config, por exemplo:

bsoncxx_cflags="$(PKG_CONFIG_PATH="$INSTALLDIR" pkg-config --cflags "libbsoncxx >= 1.2.3")"
bsoncxx_ldflags="$(PKG_CONFIG_PATH="$INSTALLDIR" pkg-config --libs "libbsoncxx >= 1.2.3")"
g++ $bsoncxx_cflags -c example-a.cpp
g++ $bsoncxx_cflags -c example-b.cpp
g++ $bsoncxx_ldflags -o example example-a.o example-b.o

Bibliotecas compartilhadas (somente MSVC)

Desde a versão 3.10.0, as bibliotecas compartilhadas, quando criadas com a cadeia de ferramentas MSVC no Windows (mesmo quando o gerador CMake não é o Visual Studio), usam um esquema de nomenclatura diferente de outras plataformas. Para restaurar o comportamento anterior, que é semelhante a outras plataformas, defina ENABLE_ABI_TAG_IN_LIBRARY_FILENAMES=OFF.

O nome das bibliotecas compartilhadas (ou seja, o "nome de saída") usa o seguinte padrão (extensão de arquivo excluída):

<basename>-v<abi-version-number>-<abi-tag>

onde:

  • <basename> corresponde à variável de configuração BSONCXX_OUTPUT_BASENAME CMake (MONGOCXX_OUTPUT_BASENAME para a biblioteca mongocxx). Por padrão, isso é definido como bsoncxx e mongocxx. O nome de base de uma biblioteca estática tem o sufixo -static.

  • <abi-version-number> corresponde ao número da versão atual da ABI.

  • <abi-tag> descreve propriedades conhecidas que afetam a compatibilidade binária da biblioteca compartilhada.

O <abi-tag> é um trio de letras que indica:

  • Tipo de construção

  • Tipo de link mongoc

  • Biblioteca polyfill

Isso é seguido por um sufixo que descreve o conjunto de ferramentas e a biblioteca de tempo de execução usados para construir a biblioteca. O conteúdo exato do sufixo depende da configuração da construção.

Exemplos de nomes de arquivos de biblioteca esperados (com uma breve descrição de funcionalidades notáveis) incluem:

  • bsoncxx-v_noabi-rhs-x64-v142-md.dll (liberar configuração de compilação)

  • bsoncxx-v_noabi-dhs-x64-v142-mdd.dll (depurar configuração de compilação)

  • bsoncxx-v_noabi-rts-x64-v142-md.dll (vinculação com bibliotecas estáticas mongoc)

  • bsoncxx-v_noabi-rhi-x64-v142-md.dll (bsoncxx como biblioteca de polyfill)

  • bsoncxx-v_noabi-rhm-x64-v142-md.dll (mnmlstc/core como biblioteca de polyfill)

  • bsoncxx-v_noabi-rhb-x64-v142-md.dll (Aumentar como biblioteca de polyfill)

  • bsoncxx-v1-rhs-x64-v142-md.dll (número da versão da ABI 1)

  • bsoncxx-v2-rhs-x64-v142-md.dll (número da versão da ABI 2)

Observação

Este exemplo também se aplica ao arquivo complementar .lib .

Esse esquema de nomenclatura permite que a biblioteca bsoncxx seja construída e instalada com diferentes configurações de construção (por exemplo Depuração vs. Versão) e diferentes requisitos de biblioteca de tempo de execução (por exemplo MultiThreadedDLL vs. MultiThreadedDebugDLL) em paralelo e sem conflito. Consulte as referências a ENABLE_ABI_TAG_IN_LIBRARY_FILENAMES e códigos relacionados na configuração do CMake para obter mais detalhes.

Por exemplo, o diretório de prefixo de instalação a seguir contém os arquivos de biblioteca de depuração e liberação esperados para uma biblioteca bsoncxx com versão 1.2.3 da API e versão da ABI 10 (o diretório bin está incluído para levar em conta os .dll arquivos ):

${CMAKE_INSTALL_PREFIX}/
├── ${CMAKE_INSTALL_BINDIR}/
│   ├── bsoncxx-v10-dhs-x64-v142-mdd.dll
│   └── bsoncxx-v10-rhs-x64-v142-md.dll
└── ${CMAKE_INSTALL_LIBDIR}/
   ├── bsoncxx-v10-dhs-x64-v142-mdd.lib
   ├── bsoncxx-v10-rhs-x64-v142-md.lib
   ├── cmake/bsoncxx-1.2.3/
   │   ├── bsoncxx-config.cmake
   │   └── ...
   └── pkgconfig/
      ├── libbsoncxx-v10-dhs-x64-v142-mdd.pc
      └── libbsoncxx-v10-rhs-x64-v142-md.pc

Os arquivos de configuração do pacote CMake são os mesmos que o comportamento regular (não MSVC) da biblioteca compartilhada descrito acima.

Observação

O CMake lida automaticamente com a seleção de bibliotecas de acordo com o tipo de compilação, mas não impõe a consistência do tipo de compilação quando apenas um tipo de compilação está instalado. A instalação das configurações de depuração e versão no Windows é altamente recomendada por esse motivo. (Esta observação se aplica somente ao parâmetro de configuração do tipo de construção).

O nome do arquivo pkg-config para bibliotecas de drivers C++ é o mesmo que para o comportamento de biblioteca compartilhada regular (não MSVC) descrito acima. No entanto, quando ENABLE_ABI_TAG_IN_PKGCONFIG_FILENAMES=ON, o nome de saída da biblioteca é usado como se fosse o nome base dos arquivos pkg-config . Por exemplo, para obter sinalizadores para a biblioteca compartilhada bsoncxx-v_noabi-rhs-x64-v142-md.dll, o comando pkg-config pode ter a seguinte aparência quando ENABLE_ABI_TAG_IN_PKGCONFIG_FILENAMES=OFF (o padrão):

pkg-config --cflags "libbsoncxx"

ou como segue quando ENABLE_ABI_TAG_IN_PKGCONFIG_FILENAMES=ON:

pkg-config --cflags "libbsoncxx-v_noabi-rhs-x64-v142-md"

A configuração ENABLE_ABI_TAG_IN_PKGCONFIG_FILENAMES=ON é recomendada para instalação paralela de bibliotecas de drivers C++ com diferentes configurações de compilação (por exemplo Depuração vs. Lançamento) é esperado. No entanto, o uso de arquivos de configuração do pacote CMake é mais recomendado.

Bibliotecas estáticas

Bibliotecas estáticas usam um padrão de nome de arquivo simples:

lib<basename>-static.a

Nenhuma informação de versão da API ou ABI está incluída no nome dos arquivos da biblioteca estática. A seleção de biblioteca compartilhada versus estática para arquivos de configuração do pacote CMake é tratada por meio de destinos do CMake. A seleção de biblioteca compartilhada versus estática para arquivos pkg-config é tratada adicionando o sufixo -static ao nome base da biblioteca, por exemplo lib<basename>-static.pc.

Por exemplo, o seguinte diretório de biblioteca contém os arquivos de biblioteca compartilhados e estáticos esperados para uma biblioteca bsoncxx:

${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_LIBDIR}/
├── libbsoncxx.so.1.2.3
├── libbsoncxx.so.10 -> libbsoncxx.so.1.2.3
├── libbsoncxx.so -> libbsoncxx.so.10
├── libbsoncxx-static.a
├── cmake/bsoncxx-1.2.3/
│   ├── bsoncxx-config.cmake
│   └── ...
└── pkgconfig/
   ├── libbsoncxx.pc
   └── libbsoncxx-static.pc

Bibliotecas estáticas (somente MSVC)

O nome das bibliotecas estáticas usa o mesmo padrão do comportamento da biblioteca compartilhada MSVC descrito acima, mas usa static como <abi-version-number> e o nome de saída da biblioteca como se fosse o nome base.

Por exemplo, o seguinte diretório de prefixo de instalação contém os arquivos de biblioteca estática e compartilhados esperados para uma biblioteca bsoncxx (o diretório bin está incluído para contabilizar os arquivos .dll ):

${CMAKE_INSTALL_PREFIX}/
├── ${CMAKE_INSTALL_BINDIR}/
│   └── bsoncxx-v10-rhs-x64-v142-md.dll
└── ${CMAKE_INSTALL_LIBDIR}/
   ├── bsoncxx-v10-rhs-x64-v142-md.lib
   ├── bsoncxx-static-dhs-x64-v142-mdd.lib
   ├── cmake/bsoncxx-1.2.3/
   │   ├── bsoncxx-config.cmake
   │   └── ...
   └── pkgconfig/
      ├── libbsoncxx-v10-rhs-x64-v142-md.pc
      └── libbsoncxx-static-rhs-x64-v142-md.pc

Voltar

Segurança de threads e forquilhas