meta: add SENTRY_DEPRECATED(msg) macro

CHANGELOG.md

@@ -12,6 +12,10 @@
 
 - Update Xbox toolchain to include `UseDebugLibraries` fix for Debug builds. ([#1302](https://github.com/getsentry/sentry-native/pull/1302))
 
+**Meta**:
+
+- Marked deprecated functions with `SENTRY_DEPRECATED(msg)`. ([#1308](https://github.com/getsentry/sentry-native/pull/1308))
+
 ## 0.9.1
 
 **Features**:

include/sentry.h

@@ -100,6 +100,25 @@ extern "C" {
 #    endif
 #endif
 
+#ifdef __has_attribute
+#    if __has_attribute(deprecated)
+#        define SENTRY_DEPRECATED(msg) __attribute__((deprecated(msg)))
+#    endif
+#endif
+#ifndef SENTRY_DEPRECATED
+#    if defined(__GNUC__)                                                      \
+        && (__GNUC__ > 4                                                       \
+            || (__GNUC__ == 4 && __GNUC_MINOR__ >= 5)) /* GCC 4.5 */
+#        define SENTRY_DEPRECATED(msg) __attribute__((deprecated(msg)))
+#    elif defined(__clang__) && __clang__major__ >= 3 /* Clang 3.0 */
+#        define SENTRY_DEPRECATED(msg) __attribute__((deprecated(msg)))
+#    elif defined(_MSC_VER) && _MSC_VER >= 1400 /* VS 2005 (8.0) */
+#        define SENTRY_DEPRECATED(msg) __declspec(deprecated(msg))
+#    else
+#        define SENTRY_DEPRECATED(msg)
+#    endif
+#endif
+
 /* marks a function as experimental api */
 #ifndef SENTRY_EXPERIMENTAL_API
 #    define SENTRY_EXPERIMENTAL_API SENTRY_API
@@ -515,13 +534,13 @@ SENTRY_EXPERIMENTAL_API char *sentry_value_to_msgpack(
  * Adds a stack trace to an event.
  *
  * The stack trace is added as part of a new thread object.
- * This function is **deprecated** in favor of using
- * `sentry_value_new_stacktrace` in combination with `sentry_value_new_thread`
- * and `sentry_event_add_thread`.
  *
  * If `ips` is NULL the current stack trace is captured, otherwise `len`
  * stack trace instruction pointers are attached to the event.
  */
+SENTRY_DEPRECATED(
+    "Use `sentry_value_new_stacktrace` in combination with "
+    "`sentry_value_new_thread` and `sentry_event_add_thread` instead")
 SENTRY_EXPERIMENTAL_API void sentry_event_value_add_stacktrace(
     sentry_value_t event, void **ips, size_t len);
 
@@ -772,11 +791,8 @@ SENTRY_API void sentry_transport_free(sentry_transport_t *transport);
  * It is a convenience function which works with a borrowed `data`, and will
  * automatically free the envelope, so the user provided function does not need
  * to do that.
- *
- * This function is *deprecated* and will be removed in a future version.
- * It is here for backwards compatibility. Users should migrate to the
- * `sentry_transport_new` API.
  */
+SENTRY_DEPRECATED("Use `sentry_transport_new` instead")
 SENTRY_API sentry_transport_t *sentry_new_function_transport(
     void (*func)(const sentry_envelope_t *envelope, void *data), void *data);
 
@@ -1053,13 +1069,13 @@ SENTRY_API const char *sentry_options_get_proxy(const sentry_options_t *opts);
 /**
  * Configures the proxy.
  *
- * This is a **deprecated** alias for `sentry_options_set_proxy(_n)`.
- *
  * The given proxy has to include the full scheme,
  * eg. `http://some.proxy/.
  */
+SENTRY_DEPRECATED("Use `sentry_options_set_proxy` instead")
 SENTRY_API void sentry_options_set_http_proxy(
     sentry_options_t *opts, const char *proxy);
+SENTRY_DEPRECATED("Use `sentry_options_set_proxy_n` instead")
 SENTRY_API void sentry_options_set_http_proxy_n(
     sentry_options_t *opts, const char *proxy, size_t proxy_len);
 
@@ -1465,10 +1481,9 @@ SENTRY_API int sentry_close(void);
 /**
  * Shuts down the sentry client and forces transports to flush out.
  *
- * This is a **deprecated** alias for `sentry_close`.
- *
  * Returns 0 on success.
  */
+SENTRY_DEPRECATED("Use `sentry_close` instead")
 SENTRY_API int sentry_shutdown(void);
 
 /**
@@ -2573,14 +2588,14 @@ SENTRY_EXPERIMENTAL_API const char *sentry_sdk_version(void);
 
 /**
  * Sentry SDK name set during build time.
- * Deprecated: Please use sentry_options_get_sdk_name instead.
  */
+SENTRY_DEPRECATED("Use `sentry_options_get_sdk_name` instead")
 SENTRY_EXPERIMENTAL_API const char *sentry_sdk_name(void);
 
 /**
  * Sentry SDK User-Agent set during build time.
- * Deprecated: Please use sentry_options_get_user_agent instead.
  */
+SENTRY_DEPRECATED("Use `sentry_options_get_user_agent` instead")
 SENTRY_EXPERIMENTAL_API const char *sentry_sdk_user_agent(void);
 
 #ifdef __cplusplus

tests/unit/sentry_testsupport.h

@@ -90,4 +90,24 @@
     sentry_dsn_t *Varname = sentry__dsn_new(DSN_URL);                          \
     TEST_ASSERT(!!Varname)
 
+#if defined(__GNUC__) || defined(__clang__)
+#    define SENTRY_TEST_DEPRECATED(call)                                       \
+        do {                                                                   \
+            _Pragma("GCC diagnostic push");                                    \
+            _Pragma("GCC diagnostic ignored \"-Wdeprecated-declarations\"");   \
+            call;                                                              \
+            _Pragma("GCC diagnostic pop");                                     \
+        } while (0)
+#elif defined(_MSC_VER)
+#    define SENTRY_TEST_DEPRECATED(call)                                       \
+        do {                                                                   \
+            __pragma(warning(push));                                           \
+            __pragma(warning(disable : 4996));                                 \
+            call;                                                              \
+            __pragma(warning(pop));                                            \
+        } while (0)
+#else
+#    define SENTRY_TEST_DEPRECATED(call) call
+#endif
+
 #endif // SENTRY_TEST_SUPPORT_H_INCLUDED

tests/unit/test_attachments.c

@@ -28,9 +28,9 @@ SENTRY_TEST(lazy_attachments)
     SENTRY_TEST_OPTIONS_NEW(options);
     sentry_options_set_auto_session_tracking(options, false);
     sentry_options_set_dsn(options, "https://[email protected]/42");
-    sentry_options_set_transport(options,
+    SENTRY_TEST_DEPRECATED(sentry_options_set_transport(options,
         sentry_new_function_transport(
-            send_envelope_test_attachments, &testdata));
+            send_envelope_test_attachments, &testdata)));
     char rel[] = { 't', 'e', 's', 't' };
     sentry_options_set_release_n(options, rel, sizeof(rel));
 

tests/unit/test_basic.c

@@ -33,8 +33,8 @@ SENTRY_TEST(basic_function_transport)
     uint64_t called = 0;
     SENTRY_TEST_OPTIONS_NEW(options);
     sentry_options_set_dsn(options, "https://[email protected]/42");
-    sentry_options_set_transport(options,
-        sentry_new_function_transport(send_envelope_test_basic, &called));
+    SENTRY_TEST_DEPRECATED(sentry_options_set_transport(options,
+        sentry_new_function_transport(send_envelope_test_basic, &called)));
     sentry_options_set_release(options, "prod");
     sentry_options_set_require_user_consent(options, true);
     sentry_init(options);
@@ -85,9 +85,9 @@ SENTRY_TEST(sampling_before_send)
 
     SENTRY_TEST_OPTIONS_NEW(options);
     sentry_options_set_dsn(options, "https://[email protected]/42");
-    sentry_options_set_transport(options,
+    SENTRY_TEST_DEPRECATED(sentry_options_set_transport(options,
         sentry_new_function_transport(
-            counting_transport_func, &called_transport));
+            counting_transport_func, &called_transport)));
     sentry_options_set_before_send(options, before_send, &called_beforesend);
     sentry_options_set_sample_rate(options, 0.75);
     sentry_init(options);
@@ -127,9 +127,9 @@ SENTRY_TEST(discarding_before_send)
     sentry_options_set_dsn(options, "https://[email protected]/42");
     // Disable sessions or this test would fail if env:SENTRY_RELEASE is set.
     sentry_options_set_auto_session_tracking(options, 0);
-    sentry_options_set_transport(options,
+    SENTRY_TEST_DEPRECATED(sentry_options_set_transport(options,
         sentry_new_function_transport(
-            counting_transport_func, &called_transport));
+            counting_transport_func, &called_transport)););
     sentry_options_set_before_send(
         options, discarding_before_send, &called_beforesend);
     sentry_init(options);

tests/unit/test_concurrency.c

@@ -22,8 +22,8 @@ init_framework(long *called)
 {
     SENTRY_TEST_OPTIONS_NEW(options);
     sentry_options_set_dsn(options, "https://[email protected]/42");
-    sentry_options_set_transport(options,
-        sentry_new_function_transport(send_envelope_test_concurrent, called));
+    SENTRY_TEST_DEPRECATED(sentry_options_set_transport(options,
+        sentry_new_function_transport(send_envelope_test_concurrent, called)));
     sentry_options_set_release(options, "prod");
     sentry_options_set_require_user_consent(options, false);
     sentry_options_set_auto_session_tracking(options, true);

tests/unit/test_failures.c

@@ -16,8 +16,9 @@ noop_send(const sentry_envelope_t *UNUSED(envelope), void *UNUSED(data))
 
 SENTRY_TEST(init_failure)
 {
-    sentry_transport_t *transport
-        = sentry_new_function_transport(noop_send, NULL);
+    sentry_transport_t *transport = NULL;
+    SENTRY_TEST_DEPRECATED(
+        transport = sentry_new_function_transport(noop_send, NULL));
     TEST_ASSERT(!!transport);
     sentry_transport_set_startup_func(transport, transport_startup_fail);
 

tests/unit/test_info.c

@@ -1,3 +1,4 @@
+#include "sentry_core.h"
 #include "sentry_testsupport.h"
 
 SENTRY_TEST(assert_sdk_version)
@@ -7,10 +8,16 @@ SENTRY_TEST(assert_sdk_version)
 
 SENTRY_TEST(assert_sdk_name)
 {
-    TEST_CHECK_STRING_EQUAL(sentry_sdk_name(), SENTRY_SDK_NAME);
+    SENTRY_WITH_OPTIONS (options) {
+        TEST_CHECK_STRING_EQUAL(
+            sentry_options_get_sdk_name(options), SENTRY_SDK_NAME);
+    }
 }
 
 SENTRY_TEST(assert_sdk_user_agent)
 {
-    TEST_CHECK_STRING_EQUAL(sentry_sdk_user_agent(), SENTRY_SDK_USER_AGENT);
+    SENTRY_WITH_OPTIONS (options) {
+        TEST_CHECK_STRING_EQUAL(
+            sentry_options_get_user_agent(options), SENTRY_SDK_USER_AGENT);
+    }
 }

tests/unit/test_session.c

@@ -57,8 +57,8 @@ SENTRY_TEST(session_basics)
     uint64_t called = 0;
     SENTRY_TEST_OPTIONS_NEW(options);
     sentry_options_set_dsn(options, "https://[email protected]/42");
-    sentry_options_set_transport(
-        options, sentry_new_function_transport(send_envelope, &called));
+    SENTRY_TEST_DEPRECATED(sentry_options_set_transport(
+        options, sentry_new_function_transport(send_envelope, &called)));
     sentry_options_set_release(options, "my_release");
 
     // the default environment is always `production` if not overwritten by the
@@ -141,8 +141,8 @@ SENTRY_TEST(count_sampled_events)
 
     SENTRY_TEST_OPTIONS_NEW(options);
     sentry_options_set_dsn(options, "https://[email protected]/42");
-    sentry_options_set_transport(options,
-        sentry_new_function_transport(send_sampled_envelope, &assertion));
+    SENTRY_TEST_DEPRECATED(sentry_options_set_transport(options,
+        sentry_new_function_transport(send_sampled_envelope, &assertion)));
     sentry_options_set_release(options, "my_release");
     sentry_options_set_sample_rate(options, 0.5);
     sentry_init(options);