Versão de API e ABI

Bibliotecas compartilhadas

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")

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)

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.

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