API 및 ABI 버전 관리
간결하게 하기 위해 이 페이지에서는 bsoncxx 라이브러리에만 적용되는 것처럼 속성 및 기능을 설명할 수 있습니다. 달리 명시되지 않는 한, 설명된 속성 및 기능은 mongocxx 라이브러리에도 유사하게 적용된다고 가정할 수 있습니다.
API 버전 관리
ABI 버전 관리
헤더 파일 구조
bsoncxx 라이브러리의 공개 헤더 파일은 ABI 네임스페이스 별로 구성됩니다.
${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_INCLUDEDIR}/ └── bsoncxx/ ├── v_noabi/bsoncxx/ │ └── ... ├── v1/bsoncxx/ │ └── ... ├── v2/bsoncxx/ │ └── ... └── vN/bsoncxx/ └── ...
이전 버전과의 호환성을 위해 ABI 네임스페이스 디렉토리 vA 의 공개 헤더 파일 에 최신 ABI 네임스페이스 디렉토리 vB 의 헤더 파일 이 포함될 수 있으며, 여기서 A < B 입니다. 이러한 상위 호환성 포함 지시문은 지원되는 경우 명시적으로 문서화됩니다. ABI 안정성이 필요한 경우, 안정적인 최신 ABI 네임스페이스 디렉토리 의 헤더를 포함하는 것이 좋습니다. ABI 안정성이 필요하지 않은 경우에는 대신 적절하고 불안정한 ABI 헤더를 포함하는 것이 좋습니다.
중요
bsoncxx/v_noabi/ 불안정한 ABI 네임스페이스 디렉토리 는 포함 경로에서 bsoncxx/ 루트 디렉토리 보다 우선순위가 높으므로 #include <bsoncxx/example.hpp> 는 #include <bsoncxx/v_noabi/bsoncxx/example.hpp> 와 동일합니다.
참고
문서화되지 않은 include 지시문의 안정성은 지원되지 않습니다.
패키지 파일은 ${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_LIBDIR}/ 의 하위 디렉토리에 설치됩니다. 사용자는 이 패키지 파일을 사용하여 bsoncxx 라이브러리 헤더(링크 및 컴파일 플래그 설정)를 가져올 것을 강력히 권장합니다. bsoncxx 헤더 파일을 가져오기 위해 포함 경로를 수동으로 구성하는 것은 권장되지 않습니다. 패키지 파일에 대해서는 아래에서 자세히 설명합니다.
모든 경우에 C++ 운전자 라이브러리를 가져올 때는 CMake 패키지 구성 파일을 사용하는 것이 좋습니다.
라이브러리 파일 이름
심볼릭 링크의 파일 이름과 존재 여부는 라이브러리를 빌드하는 데 사용된 플랫폼 및 툴체인, 라이브러리 유형(공유 및 정적)에 따라 달라집니다.
공유 라이브러리
중요
Windows에서 MSVC 도구 체인으로 구성한 경우 Windows 의 공유 라이브러리는 Windows 별 특수 고려 사항으로 인해 다르게 취급됩니다. 아래의 공유 라이브러리(MSVC만 해당) 를 참조하세요.
공유 라이브러리의 '실제 이름'은 다음 패턴 을 사용합니다.
lib<basename>.so.<api-version-number>
where:
<basename>BSONCXX_OUTPUT_BASENAMECMake 구성 변수( mongocxx 라이브러리의 경우MONGOCXX_OUTPUT_BASENAME)에 해당합니다. 기본적으로bsoncxx및mongocxx로 설정됩니다. 정적 라이브러리의 기본 이름 뒤에는-static접미사가 붙습니다.<api-version-number>지정된 빌드 구성의 MAJOR, MINOR 및 PATCH 버전으로,BUILD_VERSIONCMake 구성 변수에 해당합니다. (참고: C++ 드라이버를 정기적으로 사용할 때는 이 구성 변수를 명시적으로 설정할 필요가 없습니다.)API 버전 번호 확장자는 실제 이름에 포함 되지 않습니다 (예:
-alpha의1.2.3-alpha).
예상 라이브러리 실제 이름의 예는 다음과 같습니다.
libbsoncxx.so.1.0.0 libbsoncxx.so.2.3.4
CMake의 SOVERSION 대상 속성과 "namelink" 동작은 Linux soname 규칙에 따라 라이브러리 디렉토리에 대한 심볼릭 링크를 설치하는 데에도 사용됩니다. 이러한 심볼릭 링크에는 라이브러리 이름의 일부로 ABI 버전 번호가 포함됩니다.
예를 예시, 다음 lib 디렉토리 에는 API 버전이 1.2.3 및 ABI 버전 10 인 bsoncxx 라이브러리에 필요한 라이브러리 파일이 포함되어 있으며, 여기서 a -> b 는 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
bsoncxx 라이브러리용 CMake 패키지 의 이름은 BSONCXX_OUTPUT_BASENAME (mongocxx 라이브러리의 경우 MONGOCXX_OUTPUT_BASENAME)에 의해 제어됩니다. CMake의 구성 모드 검색 절차 에 따라 가져와야 합니다. 예를 예시, C++ 운전자 가 접두사 $INSTALLDIR 에 설치되었다고 가정합니다.
# 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")
참고
C 드라이버는 C++ 드라이버의 필수 종속성입니다. 이 종속성을 충족하기 위해 동일하거나 유사한 접근 방식을 사용하여 C 드라이버의 CMake 패키지 구성 파일을 가져와야 할 수도 있습니다.
C++ 드라이버 는 pkg-config 파일도 제공하지만, 사용자는 대신 CMake 패키지 구성 파일을 사용하는 것이 좋습니다.
bsoncxx 라이브러리의 pkg-config 파일 이름도 에 의해 제어되며 패턴을 BSONCXX_OUTPUT_NAME lib<basename>.pc따릅니다. PKG_CONFIG_PATH 환경 변수를 사용하여 pkg-config의 Atlas Search 경로를 보강해야 할 수 있습니다.
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
공유 라이브러리(MSVC만 해당)
버전 3.10.0 이후, Windows에서 MSVC 툴체인을 사용하여 빌드할 때 (CMake 생성기가 Visual Studio가 아닌 경우에도) 공유 라이브러리는 다른 플랫폼과 다른 명명 체계를 사용합니다. 다른 플랫폼과 유사한 이전 동작을 복원하려면 ENABLE_ABI_TAG_IN_LIBRARY_FILENAMES=OFF 을(를) 설정합니다.
공유 라이브러리의 이름('출력 이름'이라고도 함)은 다음 패턴을 사용합니다(파일 확장자 제외).
<basename>-v<abi-version-number>-<abi-tag>
where:
<basename>BSONCXX_OUTPUT_BASENAMECMake 구성 변수( mongocxx 라이브러리의 경우MONGOCXX_OUTPUT_BASENAME)에 해당합니다. 기본적으로bsoncxx및mongocxx로 설정됩니다. 정적 라이브러리의 기본 이름 뒤에는-static접미사가 붙습니다.<abi-version-number>현재 ABI 버전 번호에 해당합니다.<abi-tag>공유 라이브러리의 바이너리 호환성에 영향을 미치는 알려진 속성을 설명합니다.
<abi-tag> 는 다음을 나타내는 세 개의 문자입니다.
빌드 유형
mongoc 링크 유형
폴리필 라이브러리
그 뒤에 라이브러리를 빌드하는 데 사용되는 도구 세트 및 런타임 라이브러리를 설명하는 접미사가 붙습니다. 접미사의 정확한 내용은 빌드 구성에 따라 달라집니다.
예상 라이브러리 파일 이름의 예(주요 기능에 대한 간략한 설명 포함)는 다음과 같습니다.
bsoncxx-v_noabi-rhs-x64-v142-md.dll(릴리스 빌드 구성)bsoncxx-v_noabi-dhs-x64-v142-mdd.dll(디버그 빌드 구성)bsoncxx-v_noabi-rts-x64-v142-md.dll(mongoc 정적 라이브러리와 연결)bsoncxx-v_noabi-rhi-x64-v142-md.dll(bsoncxx를 폴리필 라이브러리로 사용)bsoncxx-v_noabi-rhm-x64-v142-md.dll(mnmlstc/core를 폴리필 라이브러리로 사용)bsoncxx-v_noabi-rhb-x64-v142-md.dll(Polyfill 라이브러리로 부스트)bsoncxx-v1-rhs-x64-v142-md.dll(ABI 버전 번호 1)bsoncxx-v2-rhs-x64-v142-md.dll(ABI 버전 번호 2)
참고
이 예시 는 컴패니언 .lib 파일 에도 적용됩니다.
이 명명 체계를 사용하면 bsoncxx 라이브러리를 다양한 빌드 구성으로 빌드하고 설치할 수 있습니다(예: 디버그 및 릴리스) 및 다양한 런타임 라이브러리 요구 사항(예: MultiThreadedDLL 대 MultiThreadedDebugDLL)를 충돌 없이 병렬로 실행할 수 있습니다. 자세한 내용은 CMake 구성의 ENABLE_ABI_TAG_IN_LIBRARY_FILENAMES 및 관련 코드에 대한 참조를 참조하세요.
예를 들어, 다음 설치 접두사 디렉토리에는 API 버전이 1.2.3 및 ABI 버전 10 인 bsoncxx 라이브러리에 필요한 디버그 및 릴리스 라이브러리 파일이 포함되어 있습니다(bin 디렉토리는 .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
CMake 패키지 구성 파일은 위에서 설명한 일반(MSVC가 아닌) 공유 라이브러리 동작과 동일합니다.
참고
CMake는 빌드 유형에 따라 라이브러리 선택을 자동으로 처리하지만, 하나의 빌드 유형만 설치된 경우 빌드 유형 일관성을 적용하지 않습니다. 이러한 이유로 Windows에 디버그 및 릴리스 구성을 모두 설치하는 것이 좋습니다. (이 참고 사항은 빌드 유형 구성 매개변수에만 적용됩니다).
C++ 드라이버 라이브러리의 pkg-config 파일 이름은 위에서 설명한 일반(비MSVC) 공유 라이브러리 동작의 이름과 동일합니다. 그러나 ENABLE_ABI_TAG_IN_PKGCONFIG_FILENAMES=ON 인 경우 라이브러리 출력 이름은 pkg-config 파일의 기본 이름인 것처럼 사용됩니다. 예를 들어, 공유 라이브러리 bsoncxx-v_noabi-rhs-x64-v142-md.dll 에 대한 플래그를 가져오려면 ENABLE_ABI_TAG_IN_PKGCONFIG_FILENAMES=OFF (기본값)일 때 pkg-config 명령을 다음과 같이 표시할 수 있습니다.
pkg-config --cflags "libbsoncxx"
또는 ENABLE_ABI_TAG_IN_PKGCONFIG_FILENAMES=ON 인 경우 다음과 같습니다.
pkg-config --cflags "libbsoncxx-v_noabi-rhs-x64-v142-md"
빌드 구성이 다른 C++ 드라이버 라이브러리를 병렬 설치하는 경우 ENABLE_ABI_TAG_IN_PKGCONFIG_FILENAMES=ON 로 설정하는 것이 좋습니다. 디버그 대 릴리스)가 예상됩니다. 그러나 대신 CMake 패키지 구성 파일을 사용하는 것이 가장 좋습니다.
정적 라이브러리
정적 라이브러리는 간단한 파일 이름 패턴을 사용합니다.
lib<basename>-static.a
정적 라이브러리 파일의 이름에는 API 또는 ABI 버전 정보가 포함되지 않습니다. CMake 패키지 구성 파일에 대한 공유 및 정적 라이브러리 선택은 CMake 대상을 통해 처리됩니다. pkg-config 파일에 대한 공유 및 정적 라이브러리 선택은 라이브러리 기본 이름에 -static 접미사를 추가하여 처리됩니다. lib<basename>-static.pc.
예를 들어, 다음 라이브러리 디렉토리에는 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
정적 라이브러리(MSVC만 해당)
정적 라이브러리의 이름은 위에서 설명한 MSVC 공유 라이브러리 동작과 동일한 패턴을 사용하지만, static 을 <abi-version-number> 및 라이브러리 출력 이름을 기본 이름인 것처럼 사용합니다.
예를 들어, 다음 설치 접두사 디렉토리에는 bsoncxx 라이브러리에 필요한 공유 및 정적 라이브러리 파일이 포함되어 있습니다(bin 디렉토리는 .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