Skip to content

Deprecation macros

The 2 base macros

SOFA_ATTRIBUTE_DEPRECATED(deprecateDate, disableDate, toFixMsg)

To be used to trigger a deprecation warning. It is a simple [[deprecated]] interface.

This macro warns that something

  • is DEPRECATED (still usable) since deprecateDate
  • will be disabled on disableDate

and gives the toFixMsg instructions to fix the deprecation warning.

SOFA_ATTRIBUTE_DISABLED(deprecateDate, disableDate, toFixMsg)

To be used jointly with = delete to trigger an error. It is a flavored [[deprecated]] interface.

This macro warns that something

  • is DISABLED (not usable anymore) since disabledDate
  • was firstly deprecated on deprecateDate

and gives the toFixMsg instructions to fix the compilation error.

How to use them

Create a new deprecation macro specifying the deprecation topic you are tackling. This way, you won't have dates everywhere in your code.

Example

Deprecate

I want to rename something that will break my API. To ease the transition for my users, I will propose a deprecation period with a fine message by using a deprecation macro. Latest release is v20.06, next release (currently under development) is v20.12, after that will come the v21.06.

In my config.h.in 

#define SOFA_ATTRIBUTE_DEPRECATED__MYDEPRECATIONTOPIC() \
    SOFA_ATTRIBUTE_DEPRECATED( \
        "v20.12 (PR#12345)", "v21.06", \
        "XXX must be renamed into YYY.")

In my code 

SOFA_ATTRIBUTE_DEPRECATED__MYDEPRECATIONTOPIC()
void myDeprecatedMethod();

Anyone using myDeprecatedMethod will get this warning: 

warning: 'myDeprecatedMethod' is deprecated: It is still usable but has been DEPRECATED since v20.12 (PR#12345). You have until v21.06 to fix your code. XXX must be renamed into YYY.

Disable

Now forward in time ... Latest release is v20.12, next release (currently under development) is v21.06, after that will come the v21.12. It is time to stop the deprecation period. To provide a clear message to my users, I will not remove my deprecated method but instead, I will disable it with = delete and use a deprecation macro.

In my config.h.in 

#define SOFA_ATTRIBUTE_DISABLED__MYDEPRECATIONTOPIC() \
    SOFA_ATTRIBUTE_DISABLED( \
        "v20.12 (PR#12345)", "v21.06 (PR#45678)", \
        "XXX must be renamed into YYY.")

In my code 

SOFA_ATTRIBUTE_DISABLED__MYDEPRECATIONTOPIC()
void myDeprecatedMethod() = delete;

Anyone using myDeprecatedMethod will get an error right after this warning: 

warning: 'myDeprecatedMethod' is deprecated: It is not usable anymore because it has been DISABLED since v21.06 (PR#45678) after being deprecated on v20.12 (PR#12345). XXX must be renamed into YYY.