Rewording, misc cleanup

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")

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)

docs/abi-version-policy.md

@@ -322,61 +322,70 @@ 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:
 
 ```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