El Driver C++ usa la guía de Ulrich Drepper para Definir la Estabilidad, la convención "soname" de la librería compartida de Linux y el CMake SOVERSION propiedad de destino para la versionado de ABI.
Per Ulrich Drepper:
Por lo tanto, la definición de estabilidad debe usar la interfaz documentada como base. El uso legítimo de las interfaces no debe verse afectado por cambios en la implementación; utilizar interfaces de manera no definida anula la garantía. Lo mismo ocurre con el uso de símbolos internos completamente no documentados. No se deben usar en absoluto.
Según The Linux Documentation Proyecto:
Cada librería compartida tiene un nombre especial llamado “soname”. El soname tiene el prefijo 'lib', el nombre de la librería, la frase '.so', seguido de un punto y un número de versión que se incrementa cada vez que la interfaz cambia (como excepción especial, las librerías C de nivel más bajo no comienzan con ` ` lib''). Un soname totalmente calificado incluye como prefijo el directorio en el que se encuentra; en un sistema operativo, un soname totalmente calificado es simplemente un enlace simbólico al "nombre real" de la librería compartida.*
Según La documentación de CMake:
Para librerías compartidas se pueden utilizar
VERSIONySOVERSIONpara especificar la versión de la compilación y la versión ABI, respectivamente. Al compilar o instalar, se crean enlaces simbólicos adecuados si la plataforma es compatible con enlaces simbólicos y el vinculador es compatible con so-names. Si solo se especifica uno de los dos, se asume que el que falta tiene el mismo número de versión.*
A efectos de la versión ABI, distinguimos entre el ABI estable y el ABI inestable.
El número de versión de ABI se aumenta cada vez que hay un cambio incompatible con versiones anteriores en el ABI estable, según lo definido más abajo.
Importante
El número de versión de la ABI solo comunica la estabilidad de la ABI estable. Los cambios (in)compatibles con versiones anteriores de la ABI inestable no se comunican mediante este número.
Nota
La política de versionado ABI solo es aplicable a las librerías compartidas. No se aplica a las librerías estáticas.
Compatibilidad binaria
Un namespace ABI se declara dentro del namespace principal de la librería (consulta Compatibilidad de fuente), precedido por la letra v y seguido de un número entero o _noabi.
Ejemplos de espacios de nombres ABI incluyen (en relación con el ámbito del espacio de nombres global):
bsoncxx::v_noabibsoncxx::v1bsoncxx::v2bsoncxx::v99
Un espacio de nombres ABI inestable es un espacio de nombres con el v_noabi nombre. Cualquier otro espacio de nombres ABI es un espacio de nombres ABI estable. El espacio de nombres raíz no es un espacio de nombres ABI.
El ABI estable es el conjunto de símbolos exportados que utiliza la API pública y se declara en un namespace ABI estable, con las siguientes excepciones:
El símbolo o las entidades públicas correspondientes de la API están explícitamente documentadas como experimentales o aún no preparadas para la estabilidad de ABI.
La entidad no está declarada dentro de un namespace ABI.
Incluyendo estas excepciones, todos los demás símbolos exportados se consideran parte de la ABI inestable.
Sólo se exportan los símbolos cuya entidad de API correspondiente está declarada explícitamente con una macro de exportación, como se controla mediante la propiedad de destino CXX_VISIBILITY_PRESET. Además, las entidades que se declaran inline, ya sea explícitamente (por ejemplo, con inline) o implícitamente (por ejemplo, Las definiciones de funciones de miembro en las definiciones de clases, las instanciaciones de plantillas de variables/funciones, etc. ) no se exportan, como se controla mediante la propiedad de destino VISIBILITY_INLINES_HIDDEN.
Si hay algún símbolo que deba exportarse o formar parte del ABI estable pero actualmente no lo es, envía un informe de errores.
Importante
No se admite el uso directo de símbolos exportados que eludan la API pública. Todos los símbolos exportados (estables o inestables) deben utilizarse a través de la API pública. Si hay un símbolo que debería ser exportado o formar parte de la ABI estable, pero actualmente no lo es, por favor envíanos un informe de error.
Importante
Un símbolo solo necesita ser utilizado por la API pública (incluso indirectamente) para ser considerado parte de la ABI estable. Un símbolo exportado que nunca haya sido utilizado por ninguna entidad de la API pública en ninguna versión anterior no se considera parte de la ABI estable (véase la nota anterior).
Importante
El comportamiento de un símbolo ABI estable también es parte del ABI estable. Esto es para garantizar un comportamiento de tiempo de ejecución coherente y compatible entre las bibliotecas compartidas con el mismo número de versión ABI. El comportamiento debe ser coherente con la documentación de una o más entidades públicas de la API que usen el símbolo (incluso indirectamente) de modo que no haya cambios observables en el comportamiento público de la API (dentro del alcance de lo que se documenta explícitamente) en versiones con el mismo número de ABI.
Nota
Algunas entidades que forman parte de la API pública pueden no formar parte del ABI estable (por ejemplo, funciones en línea, variables en línea e instanciaciones de plantillas de funciones y variables). Por el contrario, algunas entidades que forman parte del ABI estable pueden no formar parte de la API pública (por ejemplo, una función miembro privada exportada). Consulta API Versioning.
Compatibilidad del sistema de compilación
La política ABI estable con respecto a las propiedades del sistema de compilación es prácticamente la misma que la de la API pública (consulte Compatibilidad del sistema de compilación de API) con las siguientes diferencias:
En lugar de propiedades que afectan directamente la API pública, las propiedades que afectan directamente la ABI estable se consideran parte de la ABI estable.
El soname se considera parte de la ABI estable. Esto significa que, en contraste con la API pública,
BSONCXX_OUTPUT_NAMEse considera parte de la ABI estable, ya que tiene un impacto directo en el soname de la librería compartida bsoncxx resultante.El "soname" no es aplicable en Windows. Consulte Librerías compartidas (sólo MSVC).
Nota
Soportamos la estabilidad de la API estable por configuración de compilación. No apoyamos la compatibilidad de la API estable entre diferentes configuraciones de compilación. Por ejemplo, no se espera que una librería compartida generada con BSONCXX_OUTPUT_NAME=bsoncxx sea compatible con un programa compilado contra un ABI estable producido mediante una configuración de compilación con BSONCXX_OUTPUT_NAME=bsoncxx-custom-basename. ¡Esto es particularmente importante al usar generadores de configuración múltiple como Visual Studio!
Re-declaraciones del namespace raíz
El espacio de nombres raíz proporciona "redeclaraciones" de entidades declaradas en un espacio de nombres ABI. El espacio de nombres ABI puede diferir entre las entidades que se están redeclarando.
Por ejemplo, todas las siguientes redeclaraciones pueden estar presentes simultáneamente:
bsoncxx::example::foo-->bsoncxx::v_noabi::example::foobsoncxx::example::bar-->bsoncxx::v1::example::barbsoncxx::example::baz-->bsoncxx::v2::example::baz
Las redeclaraciones del namespace raíz están diseñadas para permitir la adición de símbolos binarios incompatibles en vB sin afectar la compatibilidad binaria de los símbolos vA. Facilitan la obsolescencia de los símbolos del ABI estable, al tiempo que brindan la oportunidad de una transición sin inconvenientes de vA a vB sin romper la compatibilidad binaria. Permiten que el código de usuario opte por las "actualizaciones de redeclaración" que reducen los cambios requeridos en el código fuente al pasar de vA a vB.
Estas actualizaciones de redeclaración tienen como objetivo facilitar una transición limpia hacia el uso de símbolos ABI obsoletos que se eliminarán en las distintas versiones. Por lo tanto, se recomienda a los usuarios utilizar las declaraciones del espacio de nombres raíz de forma predeterminada para optar por estas actualizaciones. Sin embargo, es posible que los usuarios deban usar calificadores explícitos del espacio de nombres ABI al hacer referencia a entidades de controladores de C++ en sus propias ABI estables, según su propia política de estabilidad.
La siguiente tabla de compatibilidad describe cuándo se debe aumentar el número de versión principal de la API o el número de versión de ABI debido a un cambio incompatible:
Cambiar tipo | Compatible con la fuente | Compatible con binarios |
Add a new | Sí | Sí |
Actualizar una redeclaración de | Tal vez []1 | Sí |
Eliminar un símbolo | No | Tal vez []2 |
Remover un símbolo | Tal vez []2 | No |
| [1] | Una entidad vB podría ser 100% compatible con el origen de la API vA a pesar de requerir el uso de un símbolo ABI estable nuevo e incompatible. |
| [2] | (1, 2) Un símbolo de ABI estable podría eliminarse de la API pública (por ejemplo, mediante documentación o eliminación de encabezados públicos) mientras siga proporcionando una definición de símbolo exportada para mantener la compatibilidad hacia atrás. Probablemente esto no ocurra, pero si sucede, sería un caso raro en el que los cambios incompatibles de origen y binarios pueden ser objeto de una división en publicaciones separadas. |
Importante
El entero utilizado por un espacio de nombres ABI NO corresponde directamente a un número de versión ABI. El número de versión ABI se actualiza cada vez que se produce un cambio binario incompatible, incluso si se trata de la eliminación de un solo símbolo de la ABI estable. Un aumento del número de versión ABI de A a B NO implica la descontinuación o eliminación de los símbolos declarados en el espacio de nombres ABI vA (si existe).
Obsolescencia y eliminación
La política para la obsolescencia y eliminación de símbolos en la ABI estable es la misma que para la API pública. Para obtener más información, consulte Obsolescencia y eliminación de API.
Una versión que contiene cambios incompatibles con el binario incrementará el número de versión del ABI en lugar del número de versión principal de la API. Sin embargo, es probable que cuando se aumente el número de versión ABI, también se aumente el número de versión principal de la API, ya que un cambio binario incompatible probablemente también sea un cambio de fuente incompatible.