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.
Control de versiones de API
Control de versiones ABI
Consulta Versionado de ABI.
Estructura del archivo de encabezado
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 encabezado público en un directorio de espacio de nombres ABI vA Puede incluir un archivo de encabezado en un directorio de espacio de nombres ABI vB A < B más reciente,, donde. Dichas directivas de compatibilidad con versiones posteriores, cuando sean compatibles, se documentarán explícitamente. Cuando se requiera estabilidad de ABI, recomendamos incluir encabezados del directorio de espacio de nombres ABI estable más reciente. Si no se requiere estabilidad de ABI, recomendamos incluir el encabezado ABI inestable correspondiente.
Importante
El directorio del espacio de nombres ABI inestable bsoncxx/v_noabi/ tiene prioridad antes del directorio raíz 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
No se admite la estabilidad de una directiva de inclusión no documentada.
Los archivos de paquete se instalan en los subdirectorios de ${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_LIBDIR}/. Se recomienda encarecidamente a los usuarios usar estos archivos de paquete para obtener el encabezado de la biblioteca bsoncxx (así como para la vinculación y la configuración de indicadores 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 de paquete se describen más adelante.
En todos los casos, los archivos de configuración del paquete CMake son el método recomendado para importar bibliotecas de controladores 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).
Bibliotecas compartidas
Importante
Las bibliotecas compartidas en Windows, cuando se configuran con la cadena de herramientas MSVC, se tratan de forma diferente debido a consideraciones especiales específicas de Windows. Consulte Bibliotecas compartidas (solo MSVC) a continuación.
El "nombre real" de las bibliotecas compartidas utiliza el siguiente patrón:
lib<basename>.so.<api-version-number>
dónde:
<basename>Corresponde a la variable de configuraciónBSONCXX_OUTPUT_BASENAMEde CMake (MONGOCXX_OUTPUT_BASENAMEpara la biblioteca mongocxx). Por defecto, se establece enbsoncxxymongocxx. El nombre base de una biblioteca estática tiene el sufijo-static.<api-version-number>Es la versión principal, secundaria y parche para la configuración de compilación dada, correspondiente a la variable de configuraciónBUILD_VERSIONde CMake. (Nota: no debería ser necesario configurar explícitamente esta variable de configuración en el uso habitual del controlador de C++).Las extensiones de número de versión de API no están incluidas en el nombre real (por ejemplo,
-alpha1.2.3-alphaen).
Algunos ejemplos de nombres reales de bibliotecas 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. Es posible 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 bibliotecas compartidas, al compilarse con la cadena de herramientas MSVC en Windows (incluso cuando el generador de CMake no es Visual Studio), utilizan un esquema de nombres diferente al de otras plataformas. Para restablecer el comportamiento anterior, similar al de otras plataformas, configure ENABLE_ABI_TAG_IN_LIBRARY_FILENAMES=OFF.
El nombre de las bibliotecas compartidas (también conocido como "nombre de salida") utiliza el siguiente patrón (extensión de archivo excluida):
<basename>-v<abi-version-number>-<abi-tag>
dónde:
<basename>Corresponde a la variable de configuraciónBSONCXX_OUTPUT_BASENAMEde CMake (MONGOCXX_OUTPUT_BASENAMEpara la biblioteca mongocxx). Por defecto, se establece enbsoncxxymongocxx. El nombre base de una biblioteca estática tiene el sufijo-static.<abi-version-number>corresponde al número de versión actual de ABI.<abi-tag>describe propiedades conocidas que afectan la compatibilidad binaria de la biblioteca compartida.
El <abi-tag> es un triplete de letras que indican:
Tipo de construcción
Tipo de enlace de mongoc
Biblioteca Polyfill
A continuación, se incluye un sufijo que describe el conjunto de herramientas y la biblioteca de ejecución utilizados para compilar la biblioteca. El contenido exacto del sufijo depende de la configuración de compilación.
Algunos ejemplos de nombres de archivos de biblioteca esperados (con una breve descripción de las características notables) incluyen:
bsoncxx-v_noabi-rhs-x64-v142-md.dll(configuración de compilació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 biblioteca polyfill)bsoncxx-v1-rhs-x64-v142-md.dll(Número de versión ABI 1)bsoncxx-v2-rhs-x64-v142-md.dll(Número de versión ABI 2)
Nota
Este ejemplo también se aplica al archivo complementario .lib.
Este esquema de nombres permite compilar e instalar la biblioteca bsoncxx con diferentes configuraciones de compilación (p. ej., Debug vs. Release) y diferentes requisitos de biblioteca en tiempo de ejecución (p. ej., MultiThreadedDLL vs. 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 información.
Por ejemplo, el siguiente directorio de prefijo de instalación contiene los archivos de biblioteca de depuración y lanzamiento esperados para una biblioteca bsoncxx con la versión 1.2.3 de API y la versión de ABI 10 (el directorio bin se incluye para tener en cuenta los .dll archivos):
${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 de la biblioteca compartida normal (no 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 de la siguiente manera cuando ENABLE_ABI_TAG_IN_PKGCONFIG_FILENAMES=ON:
pkg-config --cflags "libbsoncxx-v_noabi-rhs-x64-v142-md"
Se recomienda la configuración ENABLE_ABI_TAG_IN_PKGCONFIG_FILENAMES=ON cuando se espera la instalación paralela de bibliotecas de controladores de C++ con diferentes configuraciones de compilación (por ejemplo, depuración y lanzamiento). Sin embargo, lo más recomendable es usar los archivos de configuración del paquete CMake.
Bibliotecas estáticas
Las bibliotecas estáticas utilizan un patrón de nombre de archivo simple:
lib<basename>-static.a
El nombre de los archivos de biblioteca estática no incluye información sobre la versión de API ni ABI. La selección de bibliotecas compartidas o estáticas para los archivos de configuración de paquetes de CMake se gestiona mediante los destinos de CMake. La selección de bibliotecas compartidas o estáticas para los archivos pkg-config se gestiona añadiendo el sufijo -static al nombre base de la biblioteca, p. ej., lib<basename>-static.pc.
Por ejemplo, el siguiente directorio de biblioteca contiene los archivos de biblioteca compartidos y estáticos esperados para una 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 (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 compartidos y estáticos esperados para una biblioteca bsoncxx (el directorio bin se incluye para tener en cuenta los .dll archivos):
${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