El controlador C++ utiliza la guía de Ulrich Drepper para definir la estabilidad, la convención "soname" de la biblioteca compartida de Linux y CMake SOVERSION Propiedad de destino para el control de versiones ABI.
Per Ulrich Drepper:
Por lo tanto, la definición de estabilidad debe basarse en la interfaz documentada. El uso legítimo de las interfaces no debe verse afectado por cambios en la implementación; el uso indefinido de las interfaces anula la garantía. Lo mismo ocurre con el uso de símbolos internos completamente no documentados. Estos no deben utilizarse en absoluto.
Según el Proyecto de Documentación de Linux:
Cada biblioteca compartida tiene un nombre especial llamado "soname". Este nombre tiene el prefijo "lib", el nombre de la biblioteca, la frase ".so", seguido de un punto y un número de versión que se incrementa al cambiar la interfaz (como excepción, las bibliotecas de C de nivel inferior no empiezan por "lib"). Un soname completo incluye como prefijo el directorio donde se encuentra; en un sistema operativo, un soname completo es simplemente un enlace simbólico al "nombre real" de la biblioteca compartida.*
Según la documentación de CMake:
Para bibliotecas compartidas, se pueden usar
VERSIONySOVERSIONpara especificar la versión de compilación y la versión de ABI, respectivamente. Al compilar o instalar, se crean los enlaces simbólicos apropiados si la plataforma los admite y el enlazador admite nombres simbólicos. Si solo se especifica uno de ambos, se asume que el que falta tiene el mismo número de versión.*
A los efectos del control de versiones de ABI, distinguimos entre la ABI estable y la ABI inestable.
El número de versión de ABI se actualiza siempre que hay un cambio incompatible con versiones anteriores de la ABI estable, tal como se define a continuación.
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 control de versiones de ABI solo se aplica a bibliotecas compartidas. No se aplica a bibliotecas estáticas.
Compatibilidad binaria
Un espacio de nombres ABI se declara dentro del espacio de nombres raíz de la biblioteca (consulte Compatibilidad de origen), precedido por la letra v y seguido de un número entero _noabi o.
Los ejemplos de espacios de nombres ABI incluyen (en relación con el alcance 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 API públicas correspondientes están documentados explícitamente como experimentales o aún no preparados para la estabilidad de ABI.
La entidad no está declarada dentro de un espacio de nombres ABI.
Incluidas 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 omitan la API pública. Todos los símbolos exportados (estables o inestables) deben usarse a través de la API pública. Si hay algún símbolo que debería exportarse o que forma parte de la ABI estable, pero actualmente no lo está, envíe 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 forma parte de la ABI estable. Esto garantiza un comportamiento en tiempo de ejecución consistente y compatible entre bibliotecas compartidas con el mismo número de versión de ABI. El comportamiento debe ser coherente con la documentación de una o más entidades de API públicas que utilicen el símbolo (incluso indirectamente), de modo que no se observen cambios en el comportamiento de la API pública (dentro del alcance de lo documentado explícitamente) entre versiones con el mismo número de versión de ABI.
Nota
Algunas entidades que forman parte de la API pública podrían no formar parte de la ABI estable (por ejemplo, funciones en línea, variables en línea e instancias de plantilla de funciones y variables). Por el contrario, algunas entidades que forman parte de la ABI estable podrían no formar parte de la API pública (por ejemplo, una función miembro privada exportada).Consulte Control de versiones de la API.
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 impactan directamente en la API pública, las propiedades que impactan directamente en la ABI estable se consideran parte de la ABI estable.
El soname se considera parte de la ABI estable. Esto significa que, a diferencia de la API pública,
BSONCXX_OUTPUT_NAMEse considera parte de la ABI estable, ya que afecta directamente al soname de la biblioteca compartida bsoncxx resultante.El nombre "soname" no es aplicable en Windows.Consulte Bibliotecas compartidas (solo MSVC).
Nota
Respaldamos la estabilidad de la API estable por configuración de compilación. No admitimos la compatibilidad de la API estable con diferentes configuraciones de compilación. Por ejemplo, no se espera que una biblioteca compartida generada con BSONCXX_OUTPUT_NAME=bsoncxx sea compatible con un programa compilado con una ABI estable generada con una configuración de compilación BSONCXX_OUTPUT_NAME=bsoncxx-custom-basename con. (Esto es especialmente importante al usar generadores multiconfiguración como Visual Studio).
Redeclaraciones del espacio de nombres 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 variar según la entidad que se redeclare.
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 espacio de nombres 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 descontinuación de símbolos ABI estables, a la vez que brindan la oportunidad de una transición limpia de vA a vB sin afectar la compatibilidad binaria. Permiten que el código de usuario opte por "actualizaciones de redeclaración", lo que reduce los cambios necesarios 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 | Fuente compatible | 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 |
Eliminar un símbolo | Tal vez []2 | No |
| [1] | Una entidad vB podría tener un 100% de compatibilidad de origen con la API vA a pesar de requerir el uso de un nuevo símbolo ABI estable incompatible. |
| [2] | (,1 2) Un símbolo ABI estable podría eliminarse de la API pública (por ejemplo, mediante documentación o eliminándolo de los encabezados públicos) y, al mismo tiempo, proporcionar una definición de símbolo exportada para compatibilidad con versiones anteriores. Es poco probable que esto ocurra, pero si ocurre, sería un caso excepcional en el que los cambios incompatibles con el código fuente y el binario se dividirían en versiones independientes. |
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).
Desuso y eliminación
La política de desuso y eliminación de símbolos en la ABI estable es la misma que la de la API pública. Para obtener más información, consulte Desuso y eliminación de la API.
Una versión que contenga cambios binarios incompatibles aumentará el número de versión de ABI en lugar del número de versión principal de API. Sin embargo, es probable que al aumentar el número de versión de ABI, también aumente el número de versión principal de API, ya que un cambio binario incompatible probablemente también sea un cambio de origen incompatible.