ABI 버전 관리
C++ 드라이버는 ABI 버전 관리를 위해 울리히 드레퍼의 안정성 정의 가이드, Linux 공유 라이브러리 "soname" 규칙 및 CMake SOVERSION 대상 속성을 사용합니다.
Per Ulrich Drepper:
따라서 안정성의 정의는 문서화된 인터페이스를 기반으로 사용해야 합니다. 인터페이스의 합법적인 사용은 구현 변경의 영향을 받지 않아야 합니다. 정의되지 않은 방식으로 인터페이스를 사용하면 보증이 무효화됩니다. 완전히 문서화되지 않은 내부 기호를 사용할 때도 마찬가지입니다. 이러한 항목은 전혀 사용해서는 안 됩니다.
모든 공유 라이브러리에는 ` ` soname''이라는 특별한 이름이 있습니다. soname에는 접두사 ` ` lib'', 라이브러리 이름, 구문 ` ` .so'', 그 뒤에 마침표와 인터페이스가 변경될 때마다 증가하는 버전 번호가 옵니다(특수 예외로 가장 낮은 수준의 C 라이브러리는 ` ` lib''로 시작하지 않습니다). 정규화된 이름에는 다음이 접두사로 포함 디렉토리 . 작업 시스템에서 정규화된 이름은 단순히 공유 라이브러리의 ` ` 실제 이름''에 대한 심볼릭 링크일 뿐입니다.*
공유 라이브러리의 경우
VERSION및SOVERSION를 사용하여 각각 빌드 버전과 ABI 버전을 지정할 수 있습니다. 빌드하거나 설치할 때 플랫폼이 심볼릭 링크를 지원하고 링커가 이름을 지원하는 경우 적절한 심볼릭 링크가 생성됩니다. 둘 중 하나만 지정하면 누락된 항목의 버전 번호가 동일한 것으로 간주됩니다.*
ABI 버전 관리를 위해 안정적인 ABI 와 불안정한 ABI 를 구분합니다.
ABI 버전 번호는 아래에 정의된 대로 안정적인 ABI에 이전 버전과 호환되지 않는 변경 사항이 있을 때마다 변경됩니다.
중요
안정적인 ABI의 안정성만이 ABI 버전 번호로 전달됩니다. 불안정한 ABI에 대한 이전 버전과 호환되지 않는 변경 사항은 ABI 버전 번호로 전달되지 않습니다.
참고
ABI 버전 관리 정책은 공유 라이브러리 에만 적용됩니다. 정적 라이브러리에는 적용 되지 않습니다.
바이너리 호환성
ABI 네임스페이스 는 라이브러리의 루트 네임스페이스 내에서 선언되며( 소스 호환성 참조), 접두사가 문자 v 이고 그 뒤에 정수 또는 _noabi 가 붙습니다.
ABI 네임스페이스의 예는 다음과 같습니다(글로벌 네임스페이스 범위와 관련하여):
bsoncxx::v_noabibsoncxx::v1bsoncxx::v2bsoncxx::v99
불안정한 ABI 네임스페이스 는 이름이 v_noabi 인 네임스페이스입니다. 다른 모든 ABI 네임스페이스는 안정적인 ABI 네임스페이스 입니다. 루트 네임스페이스는 ABI 네임스페이스가 아닙니다.
안정적인 ABI 는 공개 API에서 사용하고 안정적인 ABI 네임스페이스에서 선언되는 내보낸 심볼 세트입니다. 단, 다음과 같은 예외가 있습니다.
기호 또는 해당 공용 API 엔터티는 실험용으로 명시적으로 문서화되어 있거나 ABI 안정성을 위한 아직 준비되지 않았습니다.
엔터티가 ABI 네임스페이스 내에서 선언되지 않았습니다.
이러한 예외를 포함하여 내보낸 다른 모든 심볼은 불안정한 ABI 의 일부로 간주됩니다.
해당 API 엔터티가 내보내기 매크로를 사용하여 명시적으로 선언된 기호만 내보내지며, 이는 CXX_VISIBILITY_PRESET 에 의해 제어됩니다. 대상 속성. 또한 inline 로 선언된 엔터티는 명시적으로(예: inline) 또는 암시적으로(예: 클래스 정의의 멤버 함수 정의, 변수/함수 템플릿 인스턴스화 등)은 VISIBILITY_INLINES_HIDDEN 에 의해 제어되는 대로 내보내 지지 않습니다 . 대상 속성.
내 보내야 하는 심볼 또는 안정적인 ABI의 일부가 있지만 현재 없는 경우 버그 보고서를 제출 하세요.
중요
공개 API를 우회하여 내보낸 기호를 직접 사용하는 것은 지원되지 않습니다. 내보낸 모든 심볼(안정 또는 불안정)은 공개 API를 통해 사용해야 합니다. 내 보내야 하는 심볼 또는 안정적인 ABI의 일부가 있지만 현재 없는 경우 버그 보고서를 제출하세요.
중요
안정적인 ABI의 일부로 간주되려면 공용 API에서 간접적으로만 심볼을 사용해야 합니다. 이전 릴리스에서 공개 API 엔터티에서 사용한 적이 없는 내 보낸 심볼은 안정적인 ABI의 일부로 간주되지 않습니다(위 참고 참조).
중요
안정적인 ABI 심볼의 동작 도 안정적인 ABI의 일부입니다. 이는 동일한 ABI 버전 번호를 가진 공유 라이브러리 간에 일관되고 호환되는 런타임 동작을 보장하기 위한 것입니다. 동작 은 동일한 ABI를 사용하는 릴리스 간에 공개 API 동작(명시적으로 문서화된 범위 내에서)에 관찰 가능한 변화가 없도록 기호를 사용하는 하나 이상의 공개 API 엔터티의 문서와(간접적으로도) 일치해야 합니다. 버전 번호.
참고
공개 API의 일부인 일부 엔터티는 안정적인 ABI의 일부가 아닐 수 있습니다(예: 인라인 함수, 인라인 변수, 함수 및 변수의 템플릿 인스턴스화). 반대로 안정적인 ABI의 일부인 일부 엔터티는 공개 API의 일부가 아닐 수 있습니다(예: 내보낸 비공개 멤버 함수). API 버전 관리를 참조하세요.
빌드 시스템 호환성
빌드 시스템의 속성에 관한 안정적인 ABI 정책은 다음과 같은 차이점이 있지만 대부분 공개 API 의 정책과 동일합니다( API 빌드 시스템 호환성 참조).
공개 API에 직접 영향을 미치는 속성 대신 안정적인 ABI에 직접 영향을 미치는 속성은 안정적인 ABI의 일부로 간주됩니다.
이름은 안정적인 ABI의 일부로 간주됩니다. 즉, 공개 API와 달리
BSONCXX_OUTPUT_NAME은 결과 bsoncxx 공유 라이브러리의 이름에 직접 영향을 미치기 때문에 안정적인 ABI의 일부로 간주됩니다."soname"은 Windows에 적용되지 않습니다. 공유 라이브러리(MSVC만 해당)를 참조하세요.
참고
빌드 구성별로 의 안정성을 stable API 지원합니다. 다양한 빌드 구성에서 의 호환성은 지원되지 않습니다.stable API 예를 들어 BSONCXX_OUTPUT_NAME=bsoncxx 로 생성된 공유 라이브러리는 BSONCXX_OUTPUT_NAME=bsoncxx-custom-basename 을 사용하여 빌드 구성을 사용하여 생성된 안정적인 ABI에 대해 컴파일된 프로그램과 호환되지 않을 것으로 예상됩니다. (이는 Visual Studio와 같은 다중 구성 생성기를 사용할 때 특히 중요합니다!)
루트 네임스페이스 재선언
루트 네임스페이스 는 ABI 네임스페이스 에 선언된 엔터티의 "재선언"을 제공합니다. ABI 네임스페이스 는 재선언되는 엔터티마다 다를 수 있습니다.
예를 들어 다음과 같은 재선언이 모두 동시에 존재할 수 있습니다.
bsoncxx::example::foo-->bsoncxx::v_noabi::example::foobsoncxx::example::bar-->bsoncxx::v1::example::barbsoncxx::example::baz-->bsoncxx::v2::example::baz
루트 네임스페이스 재선언은 vA 기호의 바이너리 호환성을 손상시키지 않고 vB 에 바이너리 호환되지 않는 기호를 추가할 수 있도록 설계되었습니다. 안정적인 ABI 기호의 사용 중단을 용이하게 하는 동시에 바이너리 호환성을 깨지 않고 vA 에서 vB 로 깔끔하게 전환할 수 있는 기회를 제공합니다. 이를 통해 사용자 코드가 vA 에서 vB 로 전환할 때 소스 코드에 필요한 변경 사항을 줄이는 "재선언 업그레이드"를 선택할 수 있습니다.
이러한 재선언 업그레이드는 릴리스 전반에서 더 이상 사용되지 않고 제거될 ABI 기호에서 완전히 벗어나도록 지원하기 위한 것입니다. 따라서 사용자는 기본적으로 루트 네임스페이스 선언을 사용하여 이러한 업그레이드를 선택하는 것이 좋습니다. 그러나 사용자는 자체 안정성 정책에 따라 자체 안정적인 ABI에서 C++ 드라이버 엔터티를 참조할 때 명시적인 ABI 네임스페이스 한정자를 사용해야 할 수도 있습니다.
다음 호환성 표에서는 호환되지 않는 변경으로 인해 API 주 버전 번호 또는 ABI 버전 번호를 변경해야 하는 경우에 대해 설명합니다.
유형 변경 | 소스 호환 | 바이너리 호환 |
새 vB 기호 추가 | 예 | 예 |
재선언을 vA 에서 vB로 업그레이드 | 예 | |
vA 기호 제거(공개 API에서) | No | |
vA 기호 제거(안정된 ABI에서) | No |
| [1] | vB 엔티티는 호환되지 않는 새로운 안정적인 ABI 기호를 사용해야 함에도 불구하고 vA API와 100% 소스 호환될 수 있습니다. |
| [2] | (1, 2) 이전 버전과의 호환성을 위해 내보낸 기호 정의를 계속 제공하면서 안정적인 ABI 기호를 공개 API 에서 제거할 수 있습니다(예: 문서화 또는 공개 헤더에서 제거를 통해). 이런 일이 발생할 가능성은 거의 없지만, 만약 발생하더라도 소스 변경 사항과 호환되지 않는 바이너리 변경 사항이 별도의 릴리스로 분할 될 수 있는 경우는 거의 없습니다. |
중요
ABI 네임스페이스 에서 사용하는 정수는 ABI 버전 번호와 직접적으로 일치하지 않습니다 . 안정적인 ABI에서 단일 심볼을 제거하는 경우에도 바이너리와 호환되지 않는 변경이 발생할 때마다 ABI 버전 번호가 변경됩니다. ABI 버전 번호가 A 에서 B 로 상향되었다고 해서 ABI 네임스페이스 vA (존재하는 경우)에 선언된 기호가 더 이상 사용되지 않거나 제거된다는 의미는 아닙니다 .
지원 중단 및 제거
안정적인 ABI에서 기호의 사용 중단 및 제거에 대한 정책은 공개 API 에 대한 정책과 동일합니다. 자세한 내용은 API 사용 중단 및 제거를 참조하세요.
바이너리와 호환되지 않는 변경 사항이 포함된 릴리스는 API 주요 버전 번호가 아닌 ABI 버전 번호를 상향 조정합니다. 그러나 바이너리 호환되지 않는 변경은 소스와 호환되지 않는 변경이기도 하므로 ABI 버전 번호가 변경되면 API 주요 버전 번호도 변경될 수 있습니다.