CDRIVER-5702 deprecate bson-cmp.h and bson-atomic.h

[kevinAlbs]

Deprecate bson-atomic.h and bson-cmp.h

Background & Motivation

These headers are planned for removal in C driver 2.0. The utility APIs are not essential to working with BSON or using the libbson API.

For simplicity, the headers were copied and symbols renamed. No attempt is made to reduce duplication between the deprecated API and non-deprecated API.

Verified with this patch build: https://spruce.mongodb.com/version/6707be7f32bc5700071e890c

Placement of BSON_GNUC_DEPRECATED in inline functions

I attempted to add BSON_GNUC_DEPRECATED after the inline function parameter list for consistency with other uses of BSON_GNUC_DEPRECATED in function declarations:

static BSON_INLINE int
bson_fn (void) BSON_GNUC_DEPRECATED
{
   return 123;
}

But this resulted in:

error: GCC does not allow '__deprecated__' attribute in this position on a function definition [-Werror,-Wgcc-compat]
 1239 | bson_fn (void) BSON_GNUC_DEPRECATED
      |                ^
/Users/kevin.albertson/code/tasks/mongo-c-driver-2.0/src/libbson/src/bson/bson-macros.h:313:46: note: expanded from macro 'BSON_GNUC_DEPRECATED'
  313 | #define BSON_GNUC_DEPRECATED __attribute__ ((__deprecated__))
      |                                              ^
1 error generated.

Therefore, the BSON_GNUC_DEPRECATED is added after the return type:

static BSON_INLINE int BSON_GNUC_DEPRECATED
bson_foo (void)
{
   return 123;
}

[kevinAlbs]

Thank you for the reviews.

Should these new headers be named common-*-private.h

Updated the atomic and cmp headers for consistency with (most) other common headers.

This also applies to mcd-string.h and bson-dsl.h

I prefer to do in a follow-up PR to limit scope of this PR.

Latest changes verified with this patch build

[kevinAlbs]

Good catch. Updated.

[eramongodb]

One last concern; otherwise, LGTM.

[ghost]

Looks good to me! It's nice to pare down the supported API.

[ghost]

I'm noticing that bson-dsl and common-atomic-private are sensitive to include order; the 'atomic' module redefines a macro (BSON_IF_GNU_LIKE) that's also used by bson-dsl. I just filed a separate issue about this, https://jira.mongodb.org/browse/CDRIVER-5755

[kevinAlbs]

The undef appears to be restored later within bson-atomic.h / common-atomic-private.h:

#ifdef BSON_USE_LEGACY_GCC_ATOMICS
#undef BSON_IF_GNU_LIKE

Is then later restored with:

#ifdef BSON_USE_LEGACY_GCC_ATOMICS
#undef BSON_IF_GNU_LIKE
#define BSON_IF_GNU_LIKE(...) __VA_ARGS__
#endif