diff --git a/CMakeLists.txt b/CMakeLists.txt index ed07a64259..2a2083c945 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -98,12 +98,26 @@ option(WITH_ABI_VERSION_2 "EXPERIMENTAL: ABI version 2 preview" OFF) file(READ "${CMAKE_CURRENT_LIST_DIR}/api/include/opentelemetry/version.h" OPENTELEMETRY_CPP_HEADER_VERSION_H) +# +# We do not want to have WITH_ABI_VERSION = "1" or "2", +# and instead prefer two distinct flags, +# WITH_ABI_VERSION_1 and WITH_ABI_VERSION_2. +# +# This allows: +# +# - to have a specific option description for each ABI +# - to mark experimental/stable/deprecated on flags, for clarity +# - to search for exact abi usage move easily, discouraging: +# cmake -DWITH_ABI_VERSION=${ARG} +# +# While not supported, +# having distinct WITH_ABI_VERSION_1 and WITH_ABI_VERSION_2 flags +# also opens the possibility to support multiple ABI concurrently, +# should that become necessary. +# if(WITH_ABI_VERSION_1 AND WITH_ABI_VERSION_2) - # While not supported yet, having distinct WITH_ABI_VERSION_1 and - # WITH_ABI_VERSION_2 flags opens the possibility to support multiple ABI - # concurrently, which is why separate flags are used here. # - # For now, only one ABI is supported in a build. + # Only one ABI is supported in a build. # message( FATAL_ERROR "Set either WITH_ABI_VERSION_1 or WITH_ABI_VERSION_2, not both") diff --git a/api/CMakeLists.txt b/api/CMakeLists.txt index b61a94b184..613c89082c 100644 --- a/api/CMakeLists.txt +++ b/api/CMakeLists.txt @@ -94,13 +94,8 @@ if(WITH_REMOVE_METER_PREVIEW) INTERFACE ENABLE_REMOVE_METER_PREVIEW) endif() -if(WITH_ABI_VERSION_2) - target_compile_definitions(opentelemetry_api - INTERFACE OPENTELEMETRY_ABI_VERSION_NO=2) -elseif(WITH_ABI_VERSION_1) - target_compile_definitions(opentelemetry_api - INTERFACE OPENTELEMETRY_ABI_VERSION_NO=1) -endif() +target_compile_definitions(opentelemetry_api + INTERFACE OPENTELEMETRY_ABI_VERSION_NO=${OPENTELEMETRY_ABI_VERSION_NO}) # A better place should be in sdk, not api if(WITH_OTLP_HTTP_SSL_PREVIEW) diff --git a/docs/abi-version-policy.md b/docs/abi-version-policy.md index f907ac978d..1dcd1c91df 100644 --- a/docs/abi-version-policy.md +++ b/docs/abi-version-policy.md @@ -322,37 +322,41 @@ option(WITH_ABI_VERSION_2 "EXPERIMENTAL: ABI version 2 preview" OFF) Instrumented applications are built against ABI v1 by default, but may ask to use ABI v2 instead. -opentelemetry-cpp produces a library for ABI v1 by default, -but can be configured to provide ABI v2 instead. +opentelemetry-cpp produces a library for stable ABI v1 by default, +but can be configured to provide experimental ABI v2 instead. Fixes introducing breaking changes can only be delivered in the experimental ABI v2. -### STABLE V1, STABLE V2 +### STABLE V1, STABLE V2, EXPERIMENTAL V3 -In this state, two ABI versions are available, +In this state, two stable ABI versions are available, the ABI offered by default is the conservative ABI v1. +Fixes introducing breaking changes can no longer be delivered ABI v2, +because it is declared stable. +An experimental ABI v3 is created. + CMake offers the following options: ```cmake option(WITH_ABI_VERSION_1 "ABI version 1" ON) option(WITH_ABI_VERSION_2 "ABI version 2" OFF) +option(WITH_ABI_VERSION_3 "EXPERIMENTAL: ABI version 3 preview" OFF) ``` -Instrumented applications are built against ABI v1 by default, -but may ask to use ABI v2 instead. +Instrumented applications are built against stable ABI v1 by default, +but may ask to use the now stable ABI v2 instead. opentelemetry-cpp produces a library for ABI v1 by default, but can be configured to provide ABI v2 instead. -Fixes introducing breaking changes can not be delivered ABI v2, because it -is declared stable. These fixes can either wait, or an experimental ABI v3 -can be created. +Fixes introducing breaking changes can only be delivered in the experimental +ABI v3. -### DEPRECATED V1, STABLE V2 +### DEPRECATED V1, STABLE V2, EXPERIMENTAL V3 -In this state, two ABI versions are available, +In this state, two stable ABI versions are available, the ABI offered by default is the newer ABI v2. CMake offers the following options: @@ -360,23 +364,28 @@ CMake offers the following options: ```cmake option(WITH_ABI_VERSION_1 "DEPRECATED: ABI version 1" OFF) option(WITH_ABI_VERSION_2 "ABI version 2" ON) +option(WITH_ABI_VERSION_3 "EXPERIMENTAL: ABI version 3 preview" OFF) ``` -Instrumented applications are built against ABI v2 by default, -but may ask to use ABI v1 instead. +Instrumented applications are built against stable ABI v2 by default, +but may ask to use stable ABI v1 instead. opentelemetry-cpp produces a library for ABI v2 by default, but can be configured to provide ABI v1 instead. -### (REMOVED V1), STABLE V2 +Fixes introducing breaking changes can only be delivered in the experimental +ABI v3. + +### (REMOVED V1), STABLE V2, EXPERIMENTAL V3 -In this state, only ABI v2 is available. +In this state, the only stable ABI available is v2. ABI v1 is no longer supported. CMake offers the following options: ```cmake option(WITH_ABI_VERSION_2 "ABI version 2" ON) +option(WITH_ABI_VERSION_3 "EXPERIMENTAL: ABI version 3 preview" OFF) ``` Instrumented applications and the opentelemetry-cpp library are build using