api: Versioned namespace to preserve ABI compatibility between minor releases (#4869)

This is a backported version of PR #4869 to minimize the textual
differences between 3.1 and 3.2 branches. In 3.1, the main
OIIO_NAMESPACE and the OIIO_3_1_NAMESPACE are the same.

---

This patch implements the new scheme that we hope will preserve ABI
compatibility across minor (yearly) releases.

Brief summary:

* We will strive to have annual minor releases (e.g., 3.1.x -> 3.2.x)
  be ABI/link backwards-compatible, as strongly as monthly patch
  releases (3.1.5 -> 3.1.6) always have been. Every-several-years
  major releases (3.x -> 4.x) are still a potential full compatibility
  break.

* Consumers of OpenImageIO don't need to change their code, and can
  just continue to refer to `OIIO::Foo` or `OIIO::Bar()` as always.

* Internally, all items in the public OIIO APIs will be in a versioned
  inner namespace, and will continue to live in the versioned
  namespace where they were first introduced, forever. (Well, until the
  next first-digit-changing major release, at which point we will clean
  up the old cruft and version everything up.)  If anything needs to
  change in an ABI-breaking way, it will be *duplicated* in the newer
  namespaces, so the old version continues to be available in the old
  namespace.

* The new header nsversions.h contains a long and detailed comment
  explaining how all the new declarations work.

---

Detailed explanation:

"Major" or "first digit" releases, which only happen once every
several years for us, are full ABI+API breaks. Previously, "minor" or
"second digit" releases, which are annual, have fully incompatible
ABIs, with separate namespaces to enforce it. Here, we are striving to
allow our annual/minor releases to no longer break ABI, to make
upgrading
easier for downstream users.

The basics are that once a symbol is introduced, it will forever live
in the namespace of that release. Subsequent release years will have
their own namespaces, but will either alias or duplicate the original
symbols.  This is enabled by our recent (in the lead-up to 3.1)
introduction of a split 2-part namespacing scheme. So 3.2 is the first
release that has the potential to perserve compatibility with 3.1 in
this way.

In this PR, I have done this for the whole codebase.  It works! -- as
measured by being able to have our automated ABI checker show 100%
back compatibility with 3.1. So currently, even though this is the
nascent 3.2 tree, everything in the public APIs live in the 3.1 ABI
namespace. And so they will remain, except for changes that cannot be
done without breaking ABI back-compatibility, which will then end up
with multiple versions in different versioned namespaces.

Let's look this over and decide if we like it. It does involve our
developers to do some hoop jumping and take extra care as we develop,
to keep things associated with the right namespaces.

Users of OpenImageIO shouldn't need to change anything on their end,
nor to be aware of this at all.

Signed-off-by: Larry Gritz <[email protected]>

Author: lgritz

.github/workflows/build-steps.yml

@@ -203,7 +203,7 @@ jobs:
             time make sphinx
       - name: Upload testsuite debugging artifacts
         uses: actions/upload-artifact@6f51ac03b9356f520e9adb1b1b7802705f340c2b # v4.5.0
-        if: ${{ failure() || inputs.build_docs == '1' || inputs.benchmark == '1' }}
+        if: ${{ failure() || inputs.build_docs == '1' || inputs.benchmark == '1' || inputs.abi_check != '' }}
         with:
           name: oiio-${{github.job}}-${{inputs.nametag}}
           path: |

src/build-scripts/ci-abicheck.bash

@@ -41,14 +41,14 @@ for lib in $LIBS ; do
     fgrep "Binary compatibility:" ${lib}-abi-results.txt
     echo -e "\x1b[33;0m"
 done
+cp -r compat_reports ${BUILDDIR_NEW}/compat_reports || true
 
 #
 # If the "Binary compatibility" summary results say anything other than 100%,
 # we fail!
 #
 for lib in $LIBS ; do
     if [[ `fgrep "Binary compatibility:" ${lib}-abi-results.txt | grep -v 100\%` != "" ]] ; then
-        cp -r compat_reports ${BUILDDIR_NEW}/compat_reports
         exit 1
     fi
 done

src/doc/Doxyfile

@@ -2189,6 +2189,8 @@ PREDEFINED             = DOXYGEN_SHOULD_SKIP_THIS \
                          OIIO_NAMESPACE_3_0_END="}" \
                          OIIO_NAMESPACE_3_1_BEGIN="namespace OIIO {" \
                          OIIO_NAMESPACE_3_1_END="}" \
+                         OIIO_NAMESPACE_3_2_BEGIN="namespace OIIO {" \
+                         OIIO_NAMESPACE_3_2_END="}" \
                          OIIO_NS_BEGIN="namespace OIIO {" \
                          OIIO_NS_END="}" \
                          OIIO_CONSTEXPR17=constexpr \

src/include/OpenImageIO/argparse.h

@@ -20,8 +20,12 @@
 #include <OpenImageIO/paramlist.h>
 #include <OpenImageIO/strutil.h>
 
+// Define symbols that let client applications determine if newly added
+// features are supported.
+#define OIIO_ARGPARSE_SUPPORTS_BRIEFUSAGE 1
+#define OIIO_ARGPARSE_SUPPORTS_HUMAN_PARAMNAME 1
 
-OIIO_NAMESPACE_BEGIN
+OIIO_NAMESPACE_3_1_BEGIN
 
 
 /////////////////////////////////////////////////////////////////////////////
@@ -173,7 +177,7 @@ OIIO_NAMESPACE_BEGIN
 
 class OIIO_UTIL_API ArgParse {
 public:
-    class Arg;  // Forward declarion of Arg
+    class Arg;  // Forward declaration of Arg
 
     // ------------------------------------------------------------------
     /// @defgroup Setting up an ArgParse
@@ -782,11 +786,4 @@ class OIIO_UTIL_API ArgParse {
     void usage() const { print_help(); }
 };
 
-
-
-// Define symbols that let client applications determine if newly added
-// features are supported.
-#define OIIO_ARGPARSE_SUPPORTS_BRIEFUSAGE 1
-#define OIIO_ARGPARSE_SUPPORTS_HUMAN_PARAMNAME 1
-
-OIIO_NAMESPACE_END
+OIIO_NAMESPACE_3_1_END

src/include/OpenImageIO/atomic.h

@@ -19,11 +19,11 @@
 
 
 
-OIIO_NAMESPACE_BEGIN
+OIIO_NAMESPACE_3_1_BEGIN
 
 using std::atomic;
-typedef atomic<int> atomic_int;
-typedef atomic<long long> atomic_ll;
+using atomic_int = atomic<int>;
+using atomic_ll  = atomic<long long>;
 
 
 
@@ -79,5 +79,4 @@ atomic_fetch_add(atomic<double>& a, double f)
     } while (true);
 }
 
-
-OIIO_NAMESPACE_END
+OIIO_NAMESPACE_3_1_END

src/include/OpenImageIO/attrdelegate.h

@@ -14,7 +14,7 @@
 #include <OpenImageIO/ustring.h>
 
 
-OIIO_NAMESPACE_BEGIN
+OIIO_NAMESPACE_3_1_BEGIN
 
 
 namespace pvt {
@@ -229,4 +229,4 @@ template<class C> class AttrDelegate {
 };
 
 
-OIIO_NAMESPACE_END
+OIIO_NAMESPACE_3_1_END

src/include/OpenImageIO/benchmark.h

@@ -24,7 +24,7 @@
 #endif
 
 
-OIIO_NAMESPACE_BEGIN
+OIIO_NAMESPACE_3_1_BEGIN
 
 /// DoNotOptimize(val) is a helper function for timing benchmarks that fools
 /// the compiler into thinking the the location 'val' is used and will not
@@ -470,6 +470,7 @@ OIIO_FORCEINLINE void clobber_all_memory() { }
 
 #endif
 
+OIIO_UTIL_API std::ostream& operator<<(std::ostream& out,
+                                       const Benchmarker& bench);
 
-
-OIIO_NAMESPACE_END
+OIIO_NAMESPACE_3_1_END

src/include/OpenImageIO/bit.h

@@ -10,7 +10,7 @@
 #include <OpenImageIO/platform.h>
 
 
-OIIO_NAMESPACE_BEGIN
+OIIO_NAMESPACE_3_1_BEGIN
 
 
 /// Standards-compliant bit cast of two equally sized types. This is used
@@ -273,4 +273,4 @@ rotl64(uint64_t x, int k)
 
 
 
-OIIO_NAMESPACE_END
+OIIO_NAMESPACE_3_1_END

src/include/OpenImageIO/color.h

@@ -12,6 +12,9 @@
 #include <OpenImageIO/typedesc.h>
 #include <OpenImageIO/ustring.h>
 
+// Preprocessor symbol to allow conditional compilation depending on
+// whether the ColorProcessor class is exposed (it was not prior to OIIO 1.9).
+#define OIIO_HAS_COLORPROCESSOR 1
 
 //
 // Some general color management information materials to have handy:
@@ -23,7 +26,12 @@
 //
 
 
-OIIO_NAMESPACE_BEGIN
+// Preprocessor symbol to allow conditional compilation depending on
+// whether the ColorConfig returns ColorProcessor shared pointers or raw.
+#define OIIO_COLORCONFIG_USES_SHARED_PTR 1
+
+
+OIIO_NAMESPACE_3_1_BEGIN
 
 /// The ColorProcessor encapsulates a baked color transformation, suitable for
 /// application to raw pixels, or ImageBuf(s). These are generated using
@@ -50,17 +58,9 @@ class OIIO_API ColorProcessor {
     }
 };
 
-// Preprocessor symbol to allow conditional compilation depending on
-// whether the ColorProcessor class is exposed (it was not prior to OIIO 1.9).
-#define OIIO_HAS_COLORPROCESSOR 1
-
 
 
-typedef std::shared_ptr<ColorProcessor> ColorProcessorHandle;
-
-// Preprocessor symbol to allow conditional compilation depending on
-// whether the ColorConfig returns ColorProcessor shared pointers or raw.
-#define OIIO_COLORCONFIG_USES_SHARED_PTR 1
+using ColorProcessorHandle = std::shared_ptr<ColorProcessor>;
 
 
 
@@ -515,4 +515,4 @@ linear_to_Rec709(float x)
 }
 
 
-OIIO_NAMESPACE_END
+OIIO_NAMESPACE_3_1_END

src/include/OpenImageIO/deepdata.h

@@ -10,12 +10,7 @@
 #include <OpenImageIO/span.h>
 #include <OpenImageIO/string_view.h>
 
-OIIO_NAMESPACE_BEGIN
-
-
-struct TypeDesc;
-class ImageSpec;
-
+OIIO_NAMESPACE_3_1_BEGIN
 
 
 /// A `DeepData` holds the contents of an image of ``deep'' pixels (multiple
@@ -209,4 +204,4 @@ class OIIO_API DeepData {
 };
 
 
-OIIO_NAMESPACE_END
+OIIO_NAMESPACE_3_1_END