Control de versiones de API y ABI

Para abreviar, esta página puede describir propiedades y características como si solo se aplicaran a la biblioteca bsoncxx. Salvo que se indique lo contrario, se puede asumir que las propiedades y características descritas son igualmente aplicables a la biblioteca mongocxx.

Versionado de API

Ver Versionado de API.

Control de versiones de ABI

Consulta Versionado de ABI.

Estructura del archivo de cabecera

Los archivos de encabezado públicos de la biblioteca bsoncxx están organizados por espacio de nombres ABI:

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

Para compatibilidad futura, un archivo de cabecera público en un directorio del espacio de nombres ABI vA puede incluir un archivo de cabecera en un directorio de espacio de nombres ABI más reciente vB, donde A < B. Dichas directivas de compatibilidad futura, cuando sean compatibles, serán documentadas explícitamente. Cuando se requiere estabilidad ABI, se recomienda incluir encabezados del directorio de namespace ABI estable más reciente. Si no se requiere estabilidad ABI, se recomienda incluir el encabezado ABI inestable adecuado en su lugar.

Importante

El directorio del namespace ABI inestable bsoncxx/v_noabi/ tiene prioridad sobre el directorio root bsoncxx/ en las rutas de inclusión, de modo que #include <bsoncxx/example.hpp> es equivalente a #include <bsoncxx/v_noabi/bsoncxx/example.hpp>.

Nota

La estabilidad de una directiva de inclusión no documentada no está soportada.

Los archivos de los paquetes se instalan en subdirectorios en ${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_LIBDIR}/. Se recomienda encarecidamente a los usuarios usar estos archivos de paquetes para obtener el encabezado de la librería bsoncxx (también para vincular y configurar banderas de compilación). No se recomienda la configuración manual de las rutas de inclusión para obtener los archivos de encabezado bsoncxx. Los archivos del paquete están descritos más abajo.

En todos los casos, los archivos de configuración del paquete CMake son el método recomendado para importar las librerías de drivers de C++.

Nombres de archivos de la biblioteca

El nombre del archivo y la presencia de enlaces simbólicos dependen de la plataforma y la cadena de herramientas utilizadas para construir la biblioteca, así como del tipo de biblioteca (compartida o estática).

Librerías Compartidas

Importante

Las librerías compartidas en Windows configuradas con la caja de herramientas MSVC en Windows se tratan de manera diferente debido a consideraciones especiales específicas de Windows. Ver Librerías compartidas (solo MSVC) a continuación.

El "nombre real" de las bibliotecas compartidas utiliza el siguiente patrón:

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

donde:

<basename> Corresponde a la variable de configuración BSONCXX_OUTPUT_BASENAME de CMake (MONGOCXX_OUTPUT_BASENAME para la biblioteca mongocxx). Por defecto, se establece en bsoncxx y mongocxx. El nombre base de una biblioteca estática tiene el sufijo -static.
<api-version-number> es la versión PRINCIPAL, SECUNDARIA y DE PARCHE para la configuración de compilación dada, correspondiente a la variable de configuración de CMake BUILD_VERSION. (Nota: no debería ser necesario establecer expresamente esta variable de configuración en el uso regular del controlador C++.)
Las extensiones de número de versión de la API no se incluyen en el nombre real (p. ej., el -alpha en 1.2.3-alpha).

Ejemplos de nombres reales de librerías esperados incluyen:

libbsoncxx.so.1.0.0
libbsoncxx.so.2.3.4

La propiedad del destino SOVERSION de CMake y el comportamiento "namelink" se utilizan también para instalar enlaces simbólicos en el directorio de la librería, coherente con la convención Linux soname. Estos enlaces simbólicos incluyen el número de versión ABI como parte del soname de la librería.

Por ejemplo, el siguiente directorio lib contiene los archivos de librería esperados para una librería bsoncxx con la versión de la API 1.2.3 y la versión ABI 10, donde a -> b indica que a es un enlace simbólico a 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

El nombre del paquete de CMake para las bibliotecas bsoncxx está controlado por BSONCXX_OUTPUT_BASENAME (MONGOCXX_OUTPUT_BASENAME para las bibliotecas mongocxx). Deben importarse según el procedimiento de búsqueda del modo de configuración de CMake. Por ejemplo, suponiendo que el controlador de C++ se instaló con el $INSTALLDIR prefijo:

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

Nota

El driver C es una dependencia obligatoria para el driver C++. Es posible que los archivos de configuración del paquete CMake para el driver C también necesiten ser importados usando el mismo enfoque (o similar) para satisfacer esta dependencia.

Aunque el controlador C++ también proporciona archivos pkg-config, se recomienda encarecidamente a los usuarios utilizar archivos de configuración de paquetes CMake en su lugar.

El nombre del archivo pkg-config para las bibliotecas bsoncxx también está controlado por BSONCXX_OUTPUT_NAME y sigue el patrón lib<basename>.pc. Puede que sea necesario usar la variable de entorno PKG_CONFIG_PATH para ampliar la ruta de búsqueda de pkg-config, por ejemplo:

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 compartidas (solo MSVC)

Desde la versión 3.10.0, las librerías compartidas cuando se compilan con la herramienta MSVC en Windows (incluso cuando el generador CMake no es Visual Studio) utilizan un esquema de nomenclatura diferente al de otras plataformas. Para restaurar el comportamiento anterior, que es similar al de otras plataformas, configura ENABLE_ABI_TAG_IN_LIBRARY_FILENAMES=OFF.

El nombre de las librerías compartidas (también conocido como el "nombre de salida") usa el siguiente patrón (extensión de archivo excluida):

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

donde:

<basename> Corresponde a la variable de configuración BSONCXX_OUTPUT_BASENAME de CMake (MONGOCXX_OUTPUT_BASENAME para la biblioteca mongocxx). Por defecto, se establece en bsoncxx y mongocxx. El nombre base de una biblioteca estática tiene el sufijo -static.
<abi-version-number> corresponde al número de versión ABI actual.
<abi-tag> describe propiedades conocidas que afectan la compatibilidad binaria de la biblioteca compartida.

El <abi-tag> es un triplete de letras que indica:

Tipo de construcción
mongoc Link Type
Biblioteca Polyfill

A esto le sigue un sufijo que describe el conjunto de herramientas y la biblioteca de tiempo de ejecución utilizados para compilar la biblioteca. El contenido exacto del sufijo depende de la configuración de la compilación.

Ejemplos de nombres de archivos de librerías esperados (con una breve descripción de funcionalidades notables) incluyen:

bsoncxx-v_noabi-rhs-x64-v142-md.dll (configuración de la versión de lanzamiento)
bsoncxx-v_noabi-dhs-x64-v142-mdd.dll (configuración de compilación de depuración)
bsoncxx-v_noabi-rts-x64-v142-md.dll (enlace con bibliotecas estáticas de mongoc)
bsoncxx-v_noabi-rhi-x64-v142-md.dll (bsoncxx como librería polyfill)
bsoncxx-v1-rhs-x64-v142-md.dll (número de versión de ABI 1)
bsoncxx-v2-rhs-x64-v142-md.dll (número de versión de ABI 2)

Nota

Este ejemplo también aplica al archivo .lib compañero.

Este esquema de nomenclatura permite que la librería bsoncxx se compile e instale con diferentes configuraciones de compilación (por ejemplo, depuración frente a publicación) y diferentes requisitos de librería de tiempo de ejecución (p. ej. MultiThreadedDLL frente a MultiThreadedDebugDLL) en paralelo y sin conflictos. Consulte las referencias a ENABLE_ABI_TAG_IN_LIBRARY_FILENAMES y el código relacionado en la configuración de CMake para obtener más detalles.

Por ejemplo, el siguiente directorio prefix de instalación contiene los archivos de biblioteca esperados de depuración y lanzamiento para una librería bsoncxx con versión API 1.2.3 y versión ABI 10 (se incluye el directorio bin para tener en cuenta los archivos .dll):

${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

Los archivos de configuración del paquete CMake son los mismos que el comportamiento estándar de la librería compartida (que no sea MSVC) descrito anteriormente.

Nota

CMake gestiona automáticamente la selección de bibliotecas según el tipo de compilación, pero no aplica la consistencia del tipo de compilación cuando solo se instala un tipo. Por este motivo, se recomienda encarecidamente instalar las configuraciones de depuración y de lanzamiento en Windows. (Esta nota solo aplica al parámetro de configuración del tipo de compilación).

El nombre del archivo pkg-config para las librerías del driver de C++ es el mismo que para el comportamiento habitual de la librería compartida (no MSVC) descrito anteriormente. Sin embargo, cuando ENABLE_ABI_TAG_IN_PKGCONFIG_FILENAMES=ON, el nombre de salida de la librería se utiliza como si fuera el nombre base para los archivos pkg-config. Por ejemplo, para obtener flags para la librería compartida bsoncxx-v_noabi-rhs-x64-v142-md.dll, el comando pkg-config puede tener el siguiente aspecto cuando ENABLE_ABI_TAG_IN_PKGCONFIG_FILENAMES=OFF (es por defecto):

pkg-config --cflags "libbsoncxx"

o como sigue cuando ENABLE_ABI_TAG_IN_PKGCONFIG_FILENAMES=ON:

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

Se recomienda configurar ENABLE_ABI_TAG_IN_PKGCONFIG_FILENAMES=ON cuando se realice una instalación paralela de las librerías del driver en C++ con diferentes configuraciones de compilación (por ejemplo, Se espera el uso de Debug vs. Release). Sin embargo, se recomienda encarecidamente utilizar archivos de configuración de paquetes CMake en su lugar.

Librerías estáticas

Las bibliotecas estáticas utilizan un patrón de nombre de archivo simple:

lib<basename>-static.a

No se incluye información de versión de API o ABI en el nombre de los archivos de librería estática. La selección entre librería compartida o estática para los archivos de configuración del paquete CMake se gestiona a través de objetivos CMake. La selección entre librería compartida o estática para los archivos pkg-config se gestiona añadiendo el sufijo -static al nombre base de la librería, por ejemplo, lib<basename>-static.pc.

Por ejemplo, el siguiente directorio de la librería contiene los archivos esperados de la librería compartida y estática de una librería 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

Librerías estáticas (solo MSVC)

El nombre de las bibliotecas estáticas utiliza el mismo patrón que el comportamiento de la biblioteca compartida MSVC descrito anteriormente, pero utiliza static como <abi-version-number> y el nombre de salida de la biblioteca como si fuera el nombre base.

Por ejemplo, el siguiente directorio de prefijo de instalación contiene los archivos de biblioteca compartida y estática esperados para una biblioteca bsoncxx (se incluye el directorio bin para tener en cuenta los archivos .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

Volver

Pruebas

Versionado de API