Add API_AVAILABLE annotations to the new Darwin APIs. (#23259)

.github/workflows/darwin.yaml

@@ -66,11 +66,19 @@ jobs:
             - name: Run iOS Build Debug
               timeout-minutes: 30
               working-directory: src/darwin/Framework
-              run: xcodebuild -target "Matter" -sdk iphoneos
+              # For now disable unguarded-availability-new warnings because we
+              # internally use APIs that we are annotating as only available on
+              # new enough versions.  Maybe we should change out deployment
+              # target versions instead?
+              run: xcodebuild -target "Matter" -sdk iphoneos OTHER_CFLAGS='${inherited} -Wno-unguarded-availability-new'
             - name: Run iOS Build Release
               timeout-minutes: 30
               working-directory: src/darwin/Framework
-              run: xcodebuild -target "Matter" -sdk iphoneos -configuration Release
+              # For now disable unguarded-availability-new warnings because we
+              # internally use APIs that we are annotating as only available on
+              # new enough versions.  Maybe we should change out deployment
+              # target versions instead?
+              run: xcodebuild -target "Matter" -sdk iphoneos -configuration Release OTHER_CFLAGS='${inherited} -Wno-unguarded-availability-new'
             - name: Clean Build
               run: xcodebuild clean
               working-directory: src/darwin/Framework
@@ -85,7 +93,11 @@ jobs:
               #
               # Enable -Wconversion by hand as well, because it seems to not be
               # enabled by default in the Xcode config.
-              run: xcodebuild -target "Matter" -sdk macosx OTHER_CFLAGS='${inherited} -Werror -Wconversion'
+              #
+              # Disable -Wunguarded-availability-new because we internally use
+              # APIs we added after our deployment target version.  Maybe we
+              # should change the deployment target version instead?
+              run: xcodebuild -target "Matter" -sdk macosx OTHER_CFLAGS='${inherited} -Werror -Wconversion -Wno-unguarded-availability-new'
               working-directory: src/darwin/Framework
             - name: Clean Build
               run: xcodebuild clean
@@ -107,10 +119,14 @@ jobs:
               continue-on-error: true
             - name: Run Framework Tests
               timeout-minutes: 15
+              # For now disable unguarded-availability-new warnings because we
+              # internally use APIs that we are annotating as only available on
+              # new enough versions.  Maybe we should change out deployment
+              # target versions instead?
               run: |
                   mkdir -p /tmp/darwin/framework-tests
                   ../../../out/debug/chip-all-clusters-app --interface-id -1 > >(tee /tmp/darwin/framework-tests/all-cluster-app.log) 2> >(tee /tmp/darwin/framework-tests/all-cluster-app-err.log >&2) &
-                  xcodebuild test -target "Matter" -scheme "Matter Framework Tests" -sdk macosx OTHER_CFLAGS='${inherited} -Werror -Wconversion -Wno-incomplete-umbrella' > >(tee /tmp/darwin/framework-tests/darwin-tests.log) 2> >(tee /tmp/darwin/framework-tests/darwin-tests-err.log >&2)
+                  xcodebuild test -target "Matter" -scheme "Matter Framework Tests" -sdk macosx OTHER_CFLAGS='${inherited} -Werror -Wconversion -Wno-incomplete-umbrella -Wno-unguarded-availability-new' > >(tee /tmp/darwin/framework-tests/darwin-tests.log) 2> >(tee /tmp/darwin/framework-tests/darwin-tests-err.log >&2)
               working-directory: src/darwin/Framework
             - name: Uploading log files
               uses: actions/upload-artifact@v2

examples/darwin-framework-tool/BUILD.gn

@@ -102,6 +102,10 @@ config("config") {
   cflags = [
     "-Wconversion",
     "-fobjc-arc",
+
+    # For now disable unguarded-availability-new warnings because we
+    # are not building against a system Matter.framework here anyway.
+    "-Wno-unguarded-availability-new",
   ]
 }
 

scripts/build/build_darwin_framework.py

@@ -53,6 +53,11 @@ def build_darwin_framework(args):
         '-derivedDataPath',
         abs_path,
         "PLATFORM_PREFERRED_ARCH={}".format(args.target_arch),
+        # For now disable unguarded-availability-new warnings because we
+        # internally use APIs that we are annotating as only available on
+        # new enough versions.  Maybe we should change out deployment
+        # target versions instead?
+        "OTHER_CFLAGS=${inherited} -Wno-unguarded-availability-new",
     ]
 
     if args.target_sdk != "macosx":

src/darwin/Framework/CHIP/MTRBaseDevice.h

@@ -92,6 +92,7 @@ typedef void (^MTRDeviceResubscriptionScheduledHandler)(NSError * error, NSNumbe
 /**
  * Handler for openCommissioningWindowWithSetupPasscode.
  */
+API_AVAILABLE(ios(16.2), macos(13.1), watchos(9.2), tvos(16.2))
 typedef void (^MTRDeviceOpenCommissioningWindowHandler)(MTRSetupPayload * _Nullable payload, NSError * _Nullable error);
 
 extern NSString * const MTRAttributePathKey;
@@ -263,7 +264,8 @@ extern NSString * const MTRArrayValueType;
                                    discriminator:(NSNumber *)discriminator
                                         duration:(NSNumber *)duration
                                            queue:(dispatch_queue_t)queue
-                                      completion:(MTRDeviceOpenCommissioningWindowHandler)completion;
+                                      completion:(MTRDeviceOpenCommissioningWindowHandler)completion
+    API_AVAILABLE(ios(16.2), macos(13.1), watchos(9.2), tvos(16.2));
 
 @end
 

src/darwin/Framework/CHIP/MTRDevice.h

@@ -155,7 +155,8 @@ typedef NS_ENUM(NSUInteger, MTRDeviceState) {
                                    discriminator:(NSNumber *)discriminator
                                         duration:(NSNumber *)duration
                                            queue:(dispatch_queue_t)queue
-                                      completion:(MTRDeviceOpenCommissioningWindowHandler)completion;
+                                      completion:(MTRDeviceOpenCommissioningWindowHandler)completion
+    API_AVAILABLE(ios(16.2), macos(13.1), watchos(9.2), tvos(16.2));
 
 @end
 

src/darwin/Framework/CHIP/MTRDeviceController.h

@@ -69,7 +69,8 @@ typedef void (^MTRDeviceConnectionCallback)(MTRBaseDevice * _Nullable device, NS
  */
 - (BOOL)setupCommissioningSessionWithPayload:(MTRSetupPayload *)payload
                                    newNodeID:(NSNumber *)newNodeID
-                                       error:(NSError * __autoreleasing *)error;
+                                       error:(NSError * __autoreleasing *)error
+    API_AVAILABLE(ios(16.2), macos(13.1), watchos(9.2), tvos(16.2));
 
 /**
  * Start pairing for a device with the given ID, using the provided setup PIN

src/darwin/Framework/CHIP/MTRSetupPayload.h

@@ -79,21 +79,23 @@ typedef NS_ENUM(NSUInteger, MTROptionalQRCodeInfoType) {
 /**
  * Generate a random Matter-valid setup passcode.
  */
-+ (NSNumber *)generateRandomSetupPasscode;
++ (NSNumber *)generateRandomSetupPasscode API_AVAILABLE(ios(16.2), macos(13.1), watchos(9.2), tvos(16.2));
 
 /**
  * Create an MTRSetupPayload with the given onboarding payload.
  *
  * Will return nil on errors (e.g. if the onboarding payload cannot be parsed).
  */
 + (MTRSetupPayload * _Nullable)setupPayloadWithOnboardingPayload:(NSString *)onboardingPayload
-                                                           error:(NSError * __autoreleasing *)error;
+                                                           error:(NSError * __autoreleasing *)error
+    API_AVAILABLE(ios(16.2), macos(13.1), watchos(9.2), tvos(16.2));
 
 /**
  * Initialize an MTRSetupPayload with the given passcode and discriminator.
  * This will pre-set version, product id, and vendor id to 0.
  */
-- (instancetype)initWithSetupPasscode:(NSNumber *)setupPasscode discriminator:(NSNumber *)discriminator;
+- (instancetype)initWithSetupPasscode:(NSNumber *)setupPasscode
+                        discriminator:(NSNumber *)discriminator API_AVAILABLE(ios(16.2), macos(13.1), watchos(9.2), tvos(16.2));
 
 /** Get 11 digit manual entry code from the setup payload. */
 - (nullable NSString *)manualEntryCode;
@@ -104,7 +106,8 @@ typedef NS_ENUM(NSUInteger, MTROptionalQRCodeInfoType) {
  * Returns nil on failure (e.g. if the setup payload does not have all the
  * information a QR code needs).
  */
-- (NSString * _Nullable)qrCodeString:(NSError * __autoreleasing *)error;
+- (NSString * _Nullable)qrCodeString:(NSError * __autoreleasing *)error
+    API_AVAILABLE(ios(16.2), macos(13.1), watchos(9.2), tvos(16.2));
 
 @end
 

src/darwin/Framework/CHIP/templates/MTRBaseClusters.zapt

@@ -32,16 +32,17 @@ NS_ASSUME_NONNULL_BEGIN
 {{#chip_server_cluster_attributes}}
 {{!Backwards compat for now: Treat DeviceTypeList as DeviceList.  Ideally we would have both, not just DeviceList. }}
 {{#*inline "attribute"}}Attribute{{#if (isStrEqual (asUpperCamelCase parent.name) "Descriptor")}}{{#if (isStrEqual (asUpperCamelCase name) "DeviceTypeList")}}DeviceList{{else}}{{asUpperCamelCase name}}{{/if}}{{else}}{{asUpperCamelCase name}}{{/if}}{{/inline}}
+{{! TODO: We need a better setup for the API_AVALABLE annotations here; this does not scale at all sanely. }}
 - (void)read{{>attribute}}With
 {{~#if_is_fabric_scoped_struct type~}}
   Params:(MTRReadParams * _Nullable)params completionHandler:
 {{~else~}}
   CompletionHandler:
 {{~/if_is_fabric_scoped_struct~}}
-(void (^)({{asObjectiveCClass type parent.name}} * _Nullable value, NSError * _Nullable error))completionHandler;
+(void (^)({{asObjectiveCClass type parent.name}} * _Nullable value, NSError * _Nullable error))completionHandler {{#if (isStrEqual (asUpperCamelCase parent.name) "TestCluster")}}{{#if (isStrEqual (asUpperCamelCase name) "WriteOnlyInt8u")}}API_AVAILABLE(ios(16.2), macos(13.1), watchos(9.2), tvos(16.2)){{/if}}{{/if}};
 {{#if isWritableAttribute}}
-- (void)write{{>attribute}}WithValue:({{asObjectiveCType type parent.name}})value completionHandler:(StatusCompletion)completionHandler;
-- (void)write{{>attribute}}WithValue:({{asObjectiveCType type parent.name}})value params:(MTRWriteParams * _Nullable)params completionHandler:(StatusCompletion)completionHandler;
+- (void)write{{>attribute}}WithValue:({{asObjectiveCType type parent.name}})value completionHandler:(StatusCompletion)completionHandler {{#if (isStrEqual (asUpperCamelCase parent.name) "TestCluster")}}{{#if (isStrEqual (asUpperCamelCase name) "WriteOnlyInt8u")}}API_AVAILABLE(ios(16.2), macos(13.1), watchos(9.2), tvos(16.2)){{/if}}{{/if}};
+- (void)write{{>attribute}}WithValue:({{asObjectiveCType type parent.name}})value params:(MTRWriteParams * _Nullable)params completionHandler:(StatusCompletion)completionHandler {{#if (isStrEqual (asUpperCamelCase parent.name) "TestCluster")}}{{#if (isStrEqual (asUpperCamelCase name) "WriteOnlyInt8u")}}API_AVAILABLE(ios(16.2), macos(13.1), watchos(9.2), tvos(16.2)){{/if}}{{/if}};
 {{/if}}
 {{#if isReportableAttribute}}
 /**
@@ -50,8 +51,8 @@ NS_ASSUME_NONNULL_BEGIN
  */
 - (void) subscribe{{>attribute}}WithMinInterval:(NSNumber * _Nonnull)minInterval  maxInterval:(NSNumber * _Nonnull)maxInterval
        params:(MTRSubscribeParams * _Nullable)params
-subscriptionEstablished:(SubscriptionEstablishedHandler _Nullable)subscriptionEstablishedHandler reportHandler:(void (^)({{asObjectiveCClass type parent.name}} * _Nullable value, NSError * _Nullable error))reportHandler;
-+ (void) read{{>attribute}}WithAttributeCache:(MTRAttributeCacheContainer *)attributeCacheContainer endpoint:(NSNumber *)endpoint queue:(dispatch_queue_t)queue completionHandler:(void (^)({{asObjectiveCClass type parent.name}} * _Nullable value, NSError * _Nullable error))completionHandler;
+subscriptionEstablished:(SubscriptionEstablishedHandler _Nullable)subscriptionEstablishedHandler reportHandler:(void (^)({{asObjectiveCClass type parent.name}} * _Nullable value, NSError * _Nullable error))reportHandler {{#if (isStrEqual (asUpperCamelCase parent.name) "TestCluster")}}{{#if (isStrEqual (asUpperCamelCase name) "WriteOnlyInt8u")}}API_AVAILABLE(ios(16.2), macos(13.1), watchos(9.2), tvos(16.2)){{/if}}{{/if}};
++ (void) read{{>attribute}}WithAttributeCache:(MTRAttributeCacheContainer *)attributeCacheContainer endpoint:(NSNumber *)endpoint queue:(dispatch_queue_t)queue completionHandler:(void (^)({{asObjectiveCClass type parent.name}} * _Nullable value, NSError * _Nullable error))completionHandler {{#if (isStrEqual (asUpperCamelCase parent.name) "TestCluster")}}{{#if (isStrEqual (asUpperCamelCase name) "WriteOnlyInt8u")}}API_AVAILABLE(ios(16.2), macos(13.1), watchos(9.2), tvos(16.2)){{/if}}{{/if}};
 {{/if}}
 {{/chip_server_cluster_attributes}}
 
@@ -76,7 +77,19 @@ typedef NS_OPTIONS({{asUnderlyingZclType name}}, {{objCEnumName ../name label}})
    {{#zcl_bitmap_items}}
    {{objCEnumName ../../name ../label}}{{objCEnumItemLabel label}} = {{asHex mask}},
    {{/zcl_bitmap_items}}
-};
+}
+{{! TODO: We need a better setup for the API_AVALABLE annotations here; this does not scale at all sanely. }}
+{{#if (isStrEqual (asUpperCamelCase ../name) "Switch")}}
+{{#if (isStrEqual (asUpperCamelCase label) "SwitchFeature")}}
+API_AVAILABLE(ios(16.2), macos(13.1), watchos(9.2), tvos(16.2))
+{{/if}}
+{{/if}}
+{{#if (isStrEqual (asUpperCamelCase ../name) "MediaPlayback")}}
+{{#if (isStrEqual (asUpperCamelCase label) "MediaPlaybackFeature")}}
+API_AVAILABLE(ios(16.2), macos(13.1), watchos(9.2), tvos(16.2))
+{{/if}}
+{{/if}}
+;
 
 {{/zcl_bitmaps}}
 {{/zcl_clusters}}

src/darwin/Framework/CHIP/templates/MTRClusterConstants.zapt

@@ -27,11 +27,12 @@ MTRClusterGlobalAttribute{{asUpperCamelCase label}}ID = {{asMEI manufacturerCode
 // Cluster {{asUpperCamelCase parent.label}} attributes
 {{/first}}
 {{#if clusterRef}}
-MTRCluster{{asUpperCamelCase parent.label}}Attribute{{asUpperCamelCase label}}ID = {{asMEI manufacturerCode code}},
+{{! TODO: We need a better setup for the API_AVALABLE annotations here; this does not scale at all sanely. }}
+MTRCluster{{asUpperCamelCase parent.label}}Attribute{{asUpperCamelCase label}}ID {{#if (isStrEqual (asUpperCamelCase parent.label) "Descriptor")}} {{#if (isStrEqual (asUpperCamelCase label) "DeviceTypeList")}}API_AVAILABLE(ios(16.2), macos(13.1), watchos(9.2), tvos(16.2)){{/if}}{{/if}} = {{asMEI manufacturerCode code}},
 {{!Backwards compat for now: DeviceList as an alias for DeviceTypeList}}
 {{#if (isStrEqual (asUpperCamelCase parent.label) "Descriptor")}}
 {{#if (isStrEqual (asUpperCamelCase label) "DeviceTypeList")}}
-MTRClusterDescriptorAttributeDeviceListID = MTRClusterDescriptorAttributeDeviceTypeListID,
+MTRClusterDescriptorAttributeDeviceListID = {{asMEI manufacturerCode code}},
 {{/if}}
 {{/if}}
 {{else}}

src/darwin/Framework/CHIP/templates/MTRClusters.zapt

@@ -34,10 +34,11 @@ NS_ASSUME_NONNULL_BEGIN
 {{#chip_server_cluster_attributes}}
 {{!Backwards compat for now: Treat DeviceTypeList as DeviceList.  Ideally we would have both, not just DeviceList. }}
 {{#*inline "attribute"}}Attribute{{#if (isStrEqual (asUpperCamelCase parent.name) "Descriptor")}}{{#if (isStrEqual (asUpperCamelCase name) "DeviceTypeList")}}DeviceList{{else}}{{asUpperCamelCase name}}{{/if}}{{else}}{{asUpperCamelCase name}}{{/if}}{{/inline}}
-- (NSDictionary<NSString *, id> *)read{{>attribute}}WithParams:(MTRReadParams * _Nullable)params;
+{{! TODO: We need a better setup for the API_AVALABLE annotations here; this does not scale at all sanely. }}
+- (NSDictionary<NSString *, id> *)read{{>attribute}}WithParams:(MTRReadParams * _Nullable)params {{#if (isStrEqual (asUpperCamelCase parent.name) "TestCluster")}}{{#if (isStrEqual (asUpperCamelCase name) "WriteOnlyInt8u")}}API_AVAILABLE(ios(16.2), macos(13.1), watchos(9.2), tvos(16.2)){{/if}}{{/if}};
 {{#if isWritableAttribute}}
-- (void)write{{>attribute}}WithValue:(NSDictionary<NSString *, id> *)dataValueDictionary expectedValueInterval:(NSNumber *)expectedValueIntervalMs;
-- (void)write{{>attribute}}WithValue:(NSDictionary<NSString *, id> *)dataValueDictionary expectedValueInterval:(NSNumber *)expectedValueIntervalMs params:(MTRWriteParams * _Nullable)params;
+- (void)write{{>attribute}}WithValue:(NSDictionary<NSString *, id> *)dataValueDictionary expectedValueInterval:(NSNumber *)expectedValueIntervalMs {{#if (isStrEqual (asUpperCamelCase parent.name) "TestCluster")}}{{#if (isStrEqual (asUpperCamelCase name) "WriteOnlyInt8u")}}API_AVAILABLE(ios(16.2), macos(13.1), watchos(9.2), tvos(16.2)){{/if}}{{/if}};
+- (void)write{{>attribute}}WithValue:(NSDictionary<NSString *, id> *)dataValueDictionary expectedValueInterval:(NSNumber *)expectedValueIntervalMs params:(MTRWriteParams * _Nullable)params {{#if (isStrEqual (asUpperCamelCase parent.name) "TestCluster")}}{{#if (isStrEqual (asUpperCamelCase name) "WriteOnlyInt8u")}}API_AVAILABLE(ios(16.2), macos(13.1), watchos(9.2), tvos(16.2)){{/if}}{{/if}};
 {{/if}}
 {{/chip_server_cluster_attributes}}
 

src/darwin/Framework/CHIP/templates/MTRStructsObjc-src.zapt

@@ -6,7 +6,8 @@ NS_ASSUME_NONNULL_BEGIN
 
 {{#zcl_clusters}}
 {{#zcl_structs}}
-@implementation MTR{{asUpperCamelCase parent.name}}Cluster{{asUpperCamelCase name}}
+{{#*inline "interfaceImpl"}}
+@implementation {{interfaceName}}
 - (instancetype)init
 {
   if (self = [super init]) {
@@ -19,7 +20,7 @@ NS_ASSUME_NONNULL_BEGIN
 
 - (id)copyWithZone:(nullable NSZone *)zone
 {
-  auto other = [[MTR{{asUpperCamelCase parent.name}}Cluster{{asUpperCamelCase name}} alloc] init];
+  auto other = [[{{interfaceName}} alloc] init];
 
   {{#zcl_struct_items}}
   other.{{asStructPropertyName label}} = self.{{asStructPropertyName label}};
@@ -35,22 +36,14 @@ NS_ASSUME_NONNULL_BEGIN
 }
 
 @end
+{{/inline}}
 
-{{!Backwards compat for now: Add a DeviceType thing that inherits from DeviceTypeStruct. }}
+{{> interfaceImpl interfaceName=(concat "MTR" (asUpperCamelCase parent.name) "Cluster" (asUpperCamelCase name))}}
+
+{{!Backwards compat for now: Add a DeviceType thing that is API-compatible with DeviceTypeStruct. }}
 {{#if (isStrEqual (asUpperCamelCase parent.name) "Descriptor")}}
 {{#if (isStrEqual (asUpperCamelCase name) "DeviceTypeStruct")}}
-@implementation MTRDescriptorClusterDeviceType
-
-- (id)copyWithZone:(nullable NSZone *)zone
-{
-    auto other = [[MTRDescriptorClusterDeviceType alloc] init];
-    other.type = self.type;
-    other.revision = self.revision;
-
-    return other;
-}
-
-@end
+{{> interfaceImpl interfaceName="MTRDescriptorClusterDeviceType"}}
 {{/if}}
 {{/if}}
 

src/darwin/Framework/CHIP/templates/MTRStructsObjc.zapt

@@ -6,7 +6,7 @@ NS_ASSUME_NONNULL_BEGIN
 
 {{#zcl_clusters}}
 {{#zcl_structs}}
-@interface MTR{{asUpperCamelCase parent.name}}Cluster{{asUpperCamelCase name}} : NSObject <NSCopying>
+{{#*inline "interfaceDecl"}}
 {{! Override the getter name because some of our properties start with things
     like "new" or "init" }}
 {{#zcl_struct_items}}
@@ -15,12 +15,22 @@ NS_ASSUME_NONNULL_BEGIN
 
 - (instancetype)init;
 - (id)copyWithZone:(nullable NSZone *)zone;
+{{/inline}}
+{{! TODO: We need a better setup for the API_AVALABLE annotations here; this does not scale at all sanely. }}
+{{#if (isStrEqual (asUpperCamelCase parent.name) "Descriptor")}}
+{{#if (isStrEqual (asUpperCamelCase name) "DeviceTypeStruct")}}
+API_AVAILABLE(ios(16.2), macos(13.1), watchos(9.2), tvos(16.2))
+{{/if}}
+{{/if}}
+@interface MTR{{asUpperCamelCase parent.name}}Cluster{{asUpperCamelCase name}} : NSObject <NSCopying>
+{{> interfaceDecl}}
 @end
 
-{{!Backwards compat for now: Add a DeviceType thing that inherits from DeviceTypeStruct. }}
+{{!Backwards compat for now: Add a DeviceType thing that is API-compatible with DeviceTypeStruct. }}
 {{#if (isStrEqual (asUpperCamelCase parent.name) "Descriptor")}}
 {{#if (isStrEqual (asUpperCamelCase name) "DeviceTypeStruct")}}
-@interface MTRDescriptorClusterDeviceType : MTRDescriptorClusterDeviceTypeStruct <NSCopying>
+@interface MTRDescriptorClusterDeviceType : NSObject <NSCopying>
+{{> interfaceDecl}}
 @end
 {{/if}}
 {{/if}}