How to deprecate a method in Objective-C

Question

We have our library we ship to our customers, and I'd like to mark some methods as "deprecated" because we changed them (like Apple does in the iPhone SDK).

I've seen the __OSX_AVAILABLE_BUT_DEPRECATED pre-processor macro, which is mapped to __AVAILABILITY_INTERNAL, which is mapped to __attribute__((deprecated))...

Well i'm a bit confused with this stuff!

Anybody knows something about that ?

kennytm · Accepted Answer · 2016-05-10T15:25:10.280

155

__attribute__((deprecated)) is the gcc way (also supported in clang) of marking a function / method as deprecated. When one is marked as "deprecated", a warning will be produced whenever anyone calls it.

The syntax for normal functions would be

__attribute__((deprecated))
void f(...) {
  ...
}

// gcc 4.5+ / clang
__attribute__((deprecated("g has been deprecated please use g2 instead")))
void g(...) {
  ...
}

and that of Objective-C methods would be

@interface MyClass : NSObject { ... }
-(void)f:(id)x __attribute__((deprecated));
...
@end

You can also mark the whole class as deprecated with

__attribute__((deprecated))
@interface DeprecatedClass : NSObject { ... }
...
@end

Apple also provides the <AvailabilityMacros.h> header which provides the DEPRECATED_ATTRIBUTE and DEPRECATED_MSG_ATTRIBUTE(msg) macros that expand to the above attributes, or nothing if the compiler doesn't support attributes. Note that this header doesn't exist outside of OS X / iOS.

Side note, if you are using Swift you use the @available attribute to deprecate an item, e.g.

@available(*, deprecated=2.0, message="no longer needed")
func f() {
    ...
}

edited May 10 '16 at 15:25

answered Feb 07 '11 at 17:28

kennytm

510,854
105
1,084
1,005

Thank you for this fast answer, I'm pretty sure it will help, I searched for a while before asking :) – Julien Feb 07 '11 at 17:34
1

I just have another question : is it possible to add a message like "Use method XXX instead" ? – Julien Feb 08 '11 at 08:24
22

@Julien: Yes: `__attribute((deprecated(use method XXX instead)))`. But this syntax is available only starting from gcc 4.5, and the version shipped with Xcode is 4.2... – kennytm Feb 08 '11 at 09:21
If I add deprecated attribute only to method declaration the compiler says "Attributes on method implementation and its declaration must match". Do I need to add smth to method implementation? – Borut Tomazin Apr 10 '12 at 13:25
@BorutTomazin: Please [ask a new question](http://stackoverflow.com/questions/ask). – kennytm Apr 10 '12 at 13:54
@KennyTM: I just did: http://stackoverflow.com/questions/10100356/how-to-properly-deprecate-a-method-in-xcode-4 – Borut Tomazin Apr 11 '12 at 05:33
2

This shouldn't be the accepted answer. It's not how Apple does it, and it's way uglier than `DEPRECATED_ATTRIBUTE` – Adlai Holler Nov 12 '15 at 23:25
It's fairly unlikely that people needing this answer will still be using an Xcode that compiles with gcc as it was removed [as of Xcode 5](https://support.enthought.com/hc/en-us/articles/204469410-OS-X-GCC-Clang-and-Cython-in-10-9-Mavericks). Does this directive work with the clang compiler? … I'd suggest the [macro alternative](http://stackoverflow.com/a/24611423/2547229). – Benjohn Dec 08 '15 at 22:57

score 76 · Answer 2 · edited Feb 27 '15 at 06:10

76

You can also use more readable define DEPRECATED_ATTRIBUTE

It defined in usr/include/AvailabilityMacros.h:

#define DEPRECATED_ATTRIBUTE        __attribute__((deprecated))
#define DEPRECATED_MSG_ATTRIBUTE(msg) __attribute((deprecated((msg))))

Objective-C methods example:

@interface MyClass : NSObject { ... }
-(void)foo:(id)x DEPRECATED_ATTRIBUTE;

// If you want to specify deprecated message:
-(void)bar:(id)x DEPRECATED_MSG_ATTRIBUTE("Use baz: method instead.");
...
@end

You can also mark the whole class as deprecated:

DEPRECATED_ATTRIBUTE
@interface DeprecatedClass : NSObject { ... }
...
@end

edited Feb 27 '15 at 06:10

BFar

2,447
22
23

answered Jul 07 '14 at 13:11

skywinder

21,291
15
93
123

2

This is the way Apple does it in iOS classes too. Probably the better method. – LunaCodeGirl Jan 15 '15 at 19:22
2

It's definitely the better method. Pity it's not the selected answer, or the higher voted answer. – Benjohn Dec 08 '15 at 22:58
how can i use `DEPRECATED_MSG_ATTRIBUTE` to mark a class as deprecated with message (like UIAlertView) – highboi Dec 07 '16 at 20:17
1

Is there the concept of 'renamed' similar to the available attributes in Swift? – Joe Susnick Aug 29 '19 at 20:07

score 18 · Answer 3 · edited Jun 20 '20 at 09:12

Swift 5.0

Deprecate any method/class/struct/protocols using @available

@available(*, deprecated, message: "Parse your data by hand instead")
func parseData() { }

@available(*, deprecated, renamed: "loadData")
func fetchData() { }

@available(swift, obsoleted: 4.1, renamed: "attemptConnection")
func testConnection() { }

@available(swift, deprecated: 4.0, obsoleted: 5.0, message: "This will be removed in v5.0; please migrate to a different API.")

Possible params:

introduced
deprecated
obsoleted
message
renamed

For more info see apple doc: Attributes

score 1 · Answer 4 · answered Aug 07 '16 at 22:43

1

If you are using C++14 in your xcode project, you may also use the [[deprecated]] or [[deprecated("reason")]] attribute that is now part of the language.

see documentation: http://en.cppreference.com/w/cpp/language/attributes

answered Aug 07 '16 at 22:43

Ant6n

1,887
1
20
26

score 0 · Answer 5 · answered Jan 01 '19 at 08:03

- FOR SWIFT CODE:

Put this right above the method: @available(*, deprecated: <#Version#>, message: <#Message#>)

example:

@available(*, deprecated: 11, message: "Use color assets instead")
public struct ColorPaletteItemResource: ColorPaletteItemResourceType {
    ...
}

How to deprecate a method in Objective-C

5 Answers5

Swift 5.0

- FOR SWIFT CODE:

Linked