api: make a 2-level namespace scheme (#4567)

TL;DR: In main, change the enclosing namespace from `OpenImageIO_v3_1`
to a 2-level scheme: `OpenImageIO::v3_1`.  This can't be backported to
the current release for obvious reasons; it is a forward-looking
change only.

More ponderous explanation follows:

We have for some time had a single namespace that contains the
version, defaulting to `OpenImageIO_v3_0` in the current release, for
example.  A namespace alias, `OIIO`, always aliases the current
namespace, so client applications can just say `OIIO::foo` without
needing to change code for every minor release (let alone if a
build-time option sets up a custom namespace).

By bumping the namespace for every minor release, we make the symbol
names themselves enforce a rigid ABI compatibility test, so you can't
accidentally compile against one minor release and link against an
older minor release. This gives us the freedom to break the ABI (link
compatibility) for each minor release, without subtle user errors.
(Doing it wrong makes a total failure to link, which is hard to miss.)

But being able to introduce ABI changes annually by changing the
enclosing namespace comes at the cost of a *complete* ABI compatibility
break with every minor release. Even classes or functions that haven't
change at all will be incompatible by virtue of their changed symbol
names.

This is an unfortunate limitation, and in an ideal world, we would
like downstream users to be able to upgrade to a newer minor release
more painlessly, and confident that they could even relink or perhaps
compile with a request to use an old ABI.

I haven't fully worked out all the details, or even if this is going
to be worth the trouble, but I think that a change we can introduce
now that will allow more flexibiity in the future is to switch to a
2-level namespace scheme, for example, `OpenImageIO::v3_1` instead of
the current `OpenImageIO_v3_1`.

The reason this might be helpful in the future is that we can use
"inline" namespaces that default to finding things that are in, say,
OpenImageIO::v3_2 without needing to specify it explicitly, while
giving the ability to explicitly give an alternate inner versioned
namespace. I haven't implemented that part here, it's reserved for
future expansion (though I have experimented with it, it does work,
but I want to discuss separately whether or not to actually do it).

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

CMakeLists.txt

@@ -141,17 +141,29 @@ if (TEX_BATCH_SIZE)
     add_compile_definitions (OIIO_TEXTURE_SIMD_BATCH_WIDTH=${TEX_BATCH_SIZE})
 endif ()
 
-# Set the default namespace
-set (${PROJ_NAME}_NAMESPACE ${PROJECT_NAME} CACHE STRING
-     "Customized outer namespace base name (version will be added)")
-option (${PROJ_NAME}_NAMESPACE_INCLUDE_PATCH
+
+# Namespace settings
+#
+# The "outer namespace" defaults to the project name, but it can be overridden
+# to allow custom builds that put everything inside a unique namespace that
+# can't conflict with default builds.
+set (${PROJ_NAME}_OUTER_NAMESPACE ${PROJECT_NAME} CACHE STRING
+     "Customized outer namespace")
+set (PROJ_NAMESPACE "${${PROJ_NAME}_OUTER_NAMESPACE}")  # synonym
+# There is also an inner namespace that is either vMAJ_MIN or vMAJ_MIN_PATCH,
+# depending on the setting of ${PROJ_NAME}_INNER_NAMESPACE_INCLUDE_PATCH.
+option (${PROJ_NAME}_INNER_NAMESPACE_INCLUDE_PATCH
         "Should the inner namespace include the patch number" ${${PROJECT_NAME}_DEV_RELEASE})
-set (PROJ_NAMESPACE "${${PROJ_NAME}_NAMESPACE}")
-set (PROJ_NAMESPACE_V "${PROJ_NAMESPACE}_v${PROJECT_VERSION_MAJOR}_${PROJECT_VERSION_MINOR}")
-if (${PROJ_NAME}_NAMESPACE_INCLUDE_PATCH)
-    set (PROJ_NAMESPACE_V "${PROJ_NAMESPACE_V}_${PROJECT_VERSION_PATCH}")
+if (${PROJ_NAME}_INNER_NAMESPACE_INCLUDE_PATCH)
+    set (PROJ_VERSION_NAMESPACE "v${PROJECT_VERSION_MAJOR}_${PROJECT_VERSION_MINOR}_${PROJECT_VERSION_PATCH}")
+else ()
+    set (PROJ_VERSION_NAMESPACE "v${PROJECT_VERSION_MAJOR}_${PROJECT_VERSION_MINOR}")
 endif ()
-message(STATUS "Setting Namespace to: ${PROJ_NAMESPACE_V}")
+# PROJ_NAMESPACE_V combines the outer and inner namespaces into one symbol
+set (PROJ_NAMESPACE_V "${PROJ_NAMESPACE}_${PROJ_VERSION_NAMESPACE}")
+message(STATUS "Outer namespace PROJ_OUTER_NAMESPACE:   ${PROJ_NAMESPACE}")
+message(STATUS "Inner namespace PROJ_VERSION_NAMESPACE: ${PROJ_VERSION_NAMESPACE}")
+message(STATUS "Joint namespace PROJ_NAMESPACE_V:       ${PROJ_NAMESPACE_V}")
 
 
 # Define OIIO_INTERNAL symbol only when building OIIO itself, will not be

src/doc/Doxyfile

@@ -718,7 +718,7 @@ SHOW_FILES             = YES
 # Folder Tree View (if specified).
 # The default value is: YES.
 
-SHOW_NAMESPACES        = YES
+SHOW_NAMESPACES        = NO
 
 # The FILE_VERSION_FILTER tag can be used to specify a program or script that
 # doxygen should invoke to get the current version for each file (typically from
@@ -2185,6 +2185,10 @@ PREDEFINED             = DOXYGEN_SHOULD_SKIP_THIS \
                          OIIO_HOSTDEVICE= \
                          OIIO_NAMESPACE_BEGIN="namespace OIIO {" \
                          OIIO_NAMESPACE_END="}" \
+                         OIIO_NAMESPACE_3_0_BEGIN="namespace OIIO {" \
+                         OIIO_NAMESPACE_3_0_END="}" \
+                         OIIO_NS_BEGIN="namespace OIIO {" \
+                         OIIO_NS_END="}" \
                          OIIO_CONSTEXPR17=constexpr \
                          OIIO_CONSTEXPR20=constexpr \
                          OIIO_IB_DEPRECATE_RAW_PTR:= \

src/include/OpenImageIO/oiioversion.h.in

@@ -116,16 +116,67 @@
 #    define OIIO_DISABLE_DEPRECATED 0
 #endif
 
-// Establish the name spaces
-namespace @PROJ_NAMESPACE_V@ { }
-namespace @PROJ_NAME@ = @PROJ_NAMESPACE_V@;
-
-// Macros to use in each file to enter and exit the right name spaces.
-#define @PROJ_NAME@_NAMESPACE @PROJ_NAMESPACE_V@
-#define @PROJ_NAME@_NAMESPACE_STRING "@PROJ_NAMESPACE_V@"
-#define @PROJ_NAME@_NAMESPACE_BEGIN namespace @PROJ_NAMESPACE_V@ {
-#define @PROJ_NAME@_NAMESPACE_END }
-#define @PROJ_NAME@_NAMESPACE_USING using namespace @PROJ_NAME@;
+// Establish the name spaces.
+//
+// The outer namespace defaults to OpenImageIO, but can be overriden at build
+// time. "OIIO" is always defined as an alias to this namespace, so client
+// software can always say `OIIO:Foo` without needing to know the custom outer
+// namespace.
+//
+// The primary inner namespace is vMAJ_MIN (or in main, vMAJ_MIN_PAT). The
+// outer namespace declares the inner namespace as "inline", so anything in it
+// is visible in OIIO by default.
+//
+// Current API symbols should declare things in the default namespace, which
+// has its version incremented with every minor (yearly) release:
+//
+//     // Foo.h
+//     OIIO_NAMESPACE_BEGIN /* implicitly means current for this version */
+//       void foo();
+//       void bar();
+//     OIIO_NAMESPACE_END
+//
+// Because the default inner namespace is "inline", client code can just refer
+// to `OIIO::Foo`, and `OIIO::v3_1::Foo` will be found (assuming that v3_1 is
+// the current inner namespace).
+//
+// Things can also be put in an explicit inner namespace, such as
+//
+//     OIIO_NS_BEGIN(v3_0)
+//        // for declarations that should be visible by explicit request only,
+//        // such as OIIO::v3_0::bar().
+//        int bar();
+//     OIIO_NS_END
+//
+// Currently, everything is defined with OIIO_NAMESPACE_BEGIN/END, and so is
+// put in the current-minor-release namespace. But the mechanisms outlined
+// above gives us the ability in the future to have multiple ABI (minor
+// release) generations of the same facilities existing simultaneously, to
+// preserve ABI compatibility even with minor version bumps.
+//
+
+namespace @PROJ_NAMESPACE@ {
+    // Current version's new inner namespace is inline so it's used by default.
+    inline namespace @PROJ_VERSION_NAMESPACE@ { }
+    // Legacy namespaces:
+    namespace v3_0 { }
+}
+namespace OIIO = @PROJ_NAMESPACE@;
+
+
+// Macros to declare things in the current version's inline namespace.
+#define OIIO_NAMESPACE_BEGIN namespace @PROJ_NAMESPACE@ { inline namespace @PROJ_VERSION_NAMESPACE@ {
+#define OIIO_NAMESPACE_END } }
+#define OIIO_CURRENT_NAMESPACE @PROJ_NAMESPACE@::@PROJ_VERSION_NAMESPACE@
+
+// Macros for defining legacy namespaces with an explicit version
+#define OIIO_NS_BEGIN(ver) namespace @PROJ_NAMESPACE@ { namespace ver {
+#define OIIO_NS_END } }
+
+// Specialty macro: Make something ABI compatible with 3.0
+#define OIIO_NAMESPACE_3_0 @PROJ_NAMESPACE@_v3_0
+#define OIIO_NAMESPACE_3_0_BEGIN namespace OIIO_NAMESPACE_3_0 {
+#define OIIO_NAMESPACE_3_0_END }
 
 
 /// Each imageio DSO/DLL should include this statement: