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 just remove my deprecated method but 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.