Change the way "provisional" works for Darwin availability. (#28105)

Instead of treating it as "not supported" and not generating code at all, generate the code but wrap some of it in MTR_ENABLE_PROVISIONAL and mark the rest with MTR_PROVISIONALLY_AVAILABLE. The definition of MTR_PROVISIONALLY_AVAILABLE in turn depends on whether MTR_ENABLE_PROVISIONAL is defined. If it's not, those things are marked as NS_UNAVAILABLE and hidden linker visibility, to avoid people depending on them. This allows compiling the framework with support for the provisional things, while making the default not support them. darwin-framework-tool is changed to set MTR_ENABLE_PROVISIONAL when YAML tests are enabled, so we can stop excluding tests from there.
project-chip · Nov 7, 2023 · 1117383 · 1117383
1 parent f6909a0
commit 1117383
Show file tree

Hide file tree

Showing 35 changed files with 258,984 additions and 120,077 deletions.
diff --git a/examples/darwin-framework-tool/BUILD.gn b/examples/darwin-framework-tool/BUILD.gn
@@ -32,9 +32,15 @@ declare_args() {
   # When config_enable_yaml_tests is false, the Matter SDK options are not available.
   if (!config_enable_yaml_tests) {
     chip_inet_config_enable_ipv4 = true
-    chip_config_network_layer_ble = true
-    is_clang = false
+    if (!defined(chip_config_network_layer_ble)) {
+      chip_config_network_layer_ble = true
+    }
+    if (!defined(is_clang)) {
+      is_clang = false
+    }
   }
+
+  enable_provisional_features = config_enable_yaml_tests
 }
 
 sdk = "macosx"
@@ -101,9 +107,15 @@ action("build-darwin-framework") {
   }
 
   if (config_enable_yaml_tests) {
-    args += [ "--enable_encoding_sentinel_enum_values" ]
+    args += [ "--enable-encoding-sentinel-enum-values" ]
   } else {
-    args += [ "--no-enable_encoding_sentinel_enum_values" ]
+    args += [ "--no-enable-encoding-sentinel-enum-values" ]
+  }
+
+  if (enable_provisional_features) {
+    args += [ "--enable-provisional-framework-features" ]
+  } else {
+    args += [ "--no-enable-provisional-framework-features" ]
   }
 
   output_name = "Matter.framework"
@@ -229,6 +241,8 @@ executable("darwin-framework-tool") {
       # pics is needed by tests
       "${chip_root}/src/app/tests/suites/pics",
     ]
+
+    defines = []
   } else {
     include_dirs = [
       "${chip_root}/config/standalone/",
@@ -260,6 +274,10 @@ executable("darwin-framework-tool") {
     }
   }
 
+  if (enable_provisional_features) {
+    defines += [ "MTR_ENABLE_PROVISIONAL=1" ]
+  }
+
   public_configs = [ ":config" ]
 
   output_dir = root_out_dir

diff --git a/examples/darwin-framework-tool/templates/commands.zapt b/examples/darwin-framework-tool/templates/commands.zapt
@@ -19,11 +19,17 @@
 
 {{#zcl_clusters}}
 {{#if (isSupported (asUpperCamelCase name preserveAcronyms=true))}}
+{{#if (isProvisional (asUpperCamelCase name preserveAcronyms=true))}}
+#if MTR_ENABLE_PROVISIONAL
+{{/if}}
 {{> cluster_header}}
 
 {{#zcl_commands}}
 {{#if (is_str_equal source 'client')}}
 {{#if (isSupported (asUpperCamelCase parent.name preserveAcronyms=true) command=(asUpperCamelCase name preserveAcronyms=true))}}
+{{#if (isProvisional (asUpperCamelCase parent.name preserveAcronyms=true) command=(asUpperCamelCase name preserveAcronyms=true))}}
+#if MTR_ENABLE_PROVISIONAL
+{{/if}}
 /*
  * Command {{asUpperCamelCase name}}
  */
@@ -90,12 +96,18 @@ private:
     {{/zcl_command_arguments}}
 };
 
+{{#if (isProvisional (asUpperCamelCase parent.name preserveAcronyms=true) command=(asUpperCamelCase name preserveAcronyms=true))}}
+#endif // MTR_ENABLE_PROVISIONAL
+{{/if}}
 {{/if}}
 {{/if}}
 {{/zcl_commands}}
 
 {{#zcl_attributes_server removeKeys='isOptional'}}
 {{#if (isSupported (asUpperCamelCase parent.name preserveAcronyms=true) attribute=(asUpperCamelCase name preserveAcronyms=true))}}
+{{#if (isProvisional (asUpperCamelCase parent.name preserveAcronyms=true) attribute=(asUpperCamelCase name preserveAcronyms=true))}}
+#if MTR_ENABLE_PROVISIONAL
+{{/if}}
 {{#*inline "cluster"}}Cluster{{asUpperCamelCase parent.name preserveAcronyms=true}}{{/inline}}
 {{#*inline "attribute"}}Attribute{{asUpperCamelCase name preserveAcronyms=true}}{{/inline}}
 
@@ -246,10 +258,16 @@ public:
     }
 };
 
+{{/if}}
+{{#if (isProvisional (asUpperCamelCase parent.name preserveAcronyms=true) attribute=(asUpperCamelCase name preserveAcronyms=true))}}
+#endif // MTR_ENABLE_PROVISIONAL
 {{/if}}
 {{/if}}
 {{/zcl_attributes_server}}
 {{/if}}
+{{#if (isProvisional (asUpperCamelCase name preserveAcronyms=true))}}
+#endif // MTR_ENABLE_PROVISIONAL
+{{/if}}
 {{/zcl_clusters}}
 
 /*----------------------------------------------------------------------------*\
@@ -259,6 +277,9 @@ public:
 {{#if (isSupported (asUpperCamelCase name preserveAcronyms=true))}}
 void registerCluster{{asUpperCamelCase name}}(Commands & commands)
 {
+{{#if (isProvisional (asUpperCamelCase name preserveAcronyms=true))}}
+#if MTR_ENABLE_PROVISIONAL
+{{/if}}
     using namespace chip::app::Clusters::{{asUpperCamelCase name}};
 
     const char * clusterName = "{{asUpperCamelCase name}}";
@@ -268,32 +289,36 @@ void registerCluster{{asUpperCamelCase name}}(Commands & commands)
         {{#zcl_commands}}
         {{#if (is_str_equal source 'client')}}
         {{#if (isSupported (asUpperCamelCase parent.name preserveAcronyms=true) command=(asUpperCamelCase name preserveAcronyms=true))}}
+        {{#if (isProvisional (asUpperCamelCase parent.name preserveAcronyms=true) command=(asUpperCamelCase name preserveAcronyms=true))}}
+        #if MTR_ENABLE_PROVISIONAL
+        {{/if}}
         make_unique<{{asUpperCamelCase parent.name}}{{asUpperCamelCase name}}>(), //
+        {{#if (isProvisional (asUpperCamelCase parent.name preserveAcronyms=true) command=(asUpperCamelCase name preserveAcronyms=true))}}
+        #endif // MTR_ENABLE_PROVISIONAL
+        {{/if}}
         {{/if}}
         {{/if}}
         {{/zcl_commands}}
         {{#zcl_attributes_server removeKeys='isOptional'}}
         {{#first}}
          make_unique<ReadAttribute>(Id), //
+         make_unique<WriteAttribute>(Id), //
+         make_unique<SubscribeAttribute>(Id), //
         {{/first}}
         {{#if (isSupported (asUpperCamelCase parent.name preserveAcronyms=true) attribute=(asUpperCamelCase name preserveAcronyms=true))}}
-        make_unique<Read{{asUpperCamelCase parent.name}}{{asUpperCamelCase name}}>(), //
+        {{#if (isProvisional (asUpperCamelCase parent.name preserveAcronyms=true) attribute=(asUpperCamelCase name preserveAcronyms=true))}}
+        #if MTR_ENABLE_PROVISIONAL
         {{/if}}
-        {{#first}}
-        make_unique<WriteAttribute>(Id), //
-        {{/first}}
-        {{#if (isSupported (asUpperCamelCase parent.name preserveAcronyms=true) attribute=(asUpperCamelCase name preserveAcronyms=true))}}
+        make_unique<Read{{asUpperCamelCase parent.name}}{{asUpperCamelCase name}}>(), //
         {{#if isWritableAttribute}}
         make_unique<Write{{asUpperCamelCase parent.name}}{{asUpperCamelCase name}}>(), //
         {{/if}}
-        {{/if}}
-        {{#first}}
-        make_unique<SubscribeAttribute>(Id), //
-        {{/first}}
-        {{#if (isSupported (asUpperCamelCase parent.name preserveAcronyms=true) attribute=(asUpperCamelCase name preserveAcronyms=true))}}
         {{#if isReportableAttribute}}
         make_unique<SubscribeAttribute{{asUpperCamelCase parent.name}}{{asUpperCamelCase name}}>(), //
         {{/if}}
+        {{#if (isProvisional (asUpperCamelCase parent.name preserveAcronyms=true) attribute=(asUpperCamelCase name preserveAcronyms=true))}}
+        #endif // MTR_ENABLE_PROVISIONAL
+        {{/if}}
         {{/if}}
         {{/zcl_attributes_server}}
         {{#zcl_events}}
@@ -305,6 +330,9 @@ void registerCluster{{asUpperCamelCase name}}(Commands & commands)
     };
 
     commands.RegisterCluster(clusterName, clusterCommands);
+{{#if (isProvisional (asUpperCamelCase name preserveAcronyms=true))}}
+#endif // MTR_ENABLE_PROVISIONAL
+{{/if}}
 }
 {{/if}}
 {{/zcl_clusters}}

diff --git a/examples/darwin-framework-tool/templates/tests/ciTests.json b/examples/darwin-framework-tool/templates/tests/ciTests.json
@@ -31,94 +31,6 @@
         "Test_TC_ACL_2_9",
         "Test_TC_ACL_2_10",
         "DL_LockUnlock",
-        "Disabled due to OperationalState not being enabled in Matter.framework for now:",
-        "TestOperationalState",
-        "Disabled due to TemperatureControl not being enabled in Matter.framework for now:",
-        "TestTemperatureControl",
-        "Disabled due to using ICD Management (ICDManagement) cluster, which is provisional on Darwin for now:",
-        "TestIcdManagementCluster",
-        "Test_TC_ICDM_1_1",
-        "Test_TC_ICDM_2_1",
-        "Disabled due to using Time Synchronization (TimeSynchronization) cluster, which is provisional on Darwin for now:",
-        "Test_TC_TIMESYNC_1_1",
-        "Test_TC_TIMESYNC_2_3",
-        "TestTimeSynchronization",
-        "Disabled due to using provisional Ceramic Filter Monitoring (CeramicFilterMonitoring) cluster:",
-        "Test_TC_CFREMON_1_1",
-        "Test_TC_CFREMON_2_1",
-        "Disabled due to using provisional Electrostatic Filter Monitoring (ElectrostaticFilterMonitoring) cluster:",
-        "Test_TC_ESFREMON_1_1",
-        "Test_TC_ESFREMON_2_1",
-        "Disabled due to using provisional Fuel Tank Monitoring (FuelTankMonitoring) cluster:",
-        "Test_TC_FTREMON_1_1",
-        "Test_TC_FTREMON_2_1",
-        "Disabled due to using provisional Ink Cartridge Monitoring (InkCartridgeMonitoring) cluster:",
-        "Test_TC_INKCREMON_1_1",
-        "Test_TC_INKCREMON_2_1",
-        "Disabled due to using provisional Ionizing Filter Monitoring (IonizingFilterMonitoring) cluster:",
-        "Test_TC_IONFREMON_1_1",
-        "Test_TC_IONFREMON_2_1",
-        "Disabled due to using provisional Ozone Filter Monitoring (OzoneFilterMonitoring) cluster:",
-        "Test_TC_OZFREMON_1_1",
-        "Test_TC_OZFREMON_2_1",
-        "Disabled due to using provisional Toner Cartridge Monitoring (TonerCartridgeMonitoring) cluster:",
-        "Test_TC_TCREMON_1_1",
-        "Test_TC_TCREMON_2_1",
-        "Disabled due to using provisional UV Filter Monitoring (UVFilterMonitoring) cluster:",
-        "Test_TC_UVFREMON_1_1",
-        "Test_TC_UVFREMON_2_1",
-        "Disabled due to using provisional Water Tank Monitoring (WaterTankMonitoring) cluster:",
-        "Test_TC_WTREMON_1_1",
-        "Test_TC_WTREMON_2_1",
-        "Disabled due to using provisional Zeolite Filter Monitoring (ZeoliteFilterMonitoring) cluster:",
-        "Test_TC_ZEOFREMON_1_1",
-        "Test_TC_ZEOFREMON_2_1",
-        "Disabled due to AirQuality not being enabled in Matter.framework for now:",
-        "Test_TC_AIRQUAL_1_1",
-        "Test_TC_AIRQUAL_2_1",
-        "Disabled due to CarbonDioxideConcentrationMeasurement not being enabled in Matter.framework for now:",
-        "Test_TC_CDOCONC_1_1",
-        "Test_TC_CDOCONC_2_1",
-        "Disabled due to CarbonMonoxideConcentrationMeasurement not being enabled in Matter.framework for now:",
-        "Test_TC_CMOCONC_1_1",
-        "Test_TC_CMOCONC_2_1",
-        "Disabled due to FormaldehydeConcentrationMeasurement not being enabled in Matter.framework for now:",
-        "Test_TC_FLDCONC_1_1",
-        "Test_TC_FLDCONC_2_1",
-        "Disabled due to NitrogenDioxideConcentrationMeasurement not being enabled in Matter.framework for now:",
-        "Test_TC_NDOCONC_1_1",
-        "Test_TC_NDOCONC_2_1",
-        "Disabled due to OzoneConcentrationMeasurement not being enabled in Matter.framework for now:",
-        "Test_TC_OZCONC_1_1",
-        "Test_TC_OZCONC_2_1",
-        "Disabled due to PM1ConcentrationMeasurement not being enabled in Matter.framework for now:",
-        "Test_TC_PMHCONC_1_1",
-        "Test_TC_PMHCONC_2_1",
-        "Disabled due to PM2.5ConcentrationMeasurement not being enabled in Matter.framework for now:",
-        "Test_TC_PMICONC_1_1",
-        "Test_TC_PMICONC_2_1",
-        "Disabled due to PM10ConcentrationMeasurement not being enabled in Matter.framework for now:",
-        "Test_TC_PMKCONC_1_1",
-        "Test_TC_PMKCONC_2_1",
-        "Disabled due to RadonConcentrationMeasurement not being enabled in Matter.framework for now:",
-        "Test_TC_RNCONC_1_1",
-        "Test_TC_RNCONC_2_1",
-        "Disabled due to TotalVolatileOrganicCompoundsConcentrationMeasurement not being enabled in Matter.framework for now:",
-        "Test_TC_TVOCCONC_1_1",
-        "Test_TC_TVOCCONC_2_1",
-        "Disabled due to FanControl AirFlowDirection attribute not being enabled in Matter.framework for now:",
-        "Test_TC_FAN_2_5",
-        "Disabled due to DoorLock UnboltDoor command not being enabled in Matter.framework for now:",
-        "Test_TC_DRLK_2_12",
-        "DL_LockUnlock",
-        "Disabled due to ActivatedCarbonFilterMonitoring not being enabled in Matter.framework for now:",
-        "Test_TC_ACFREMON_1_1",
-        "Test_TC_ACFREMON_2_1",
-        "Disabled due to HEPAFilterMonitoring not being enabled in Matter.framework for now:",
-        "Test_TC_HEPAFREMON_1_1",
-        "Test_TC_HEPAFREMON_2_1",
-        "Disabled due to OperationalState not being enabled in Matter.framework for now:",
-        "Test_TC_OPSTATE_1_1",
         "Disabled due to Events verification not supported",
         "Test_TC_BINFO_2_2",
         "Test_TC_ACL_2_5",

diff --git a/examples/darwin-framework-tool/templates/tests/partials/check_test_value.zapt b/examples/darwin-framework-tool/templates/tests/partials/check_test_value.zapt
@@ -30,7 +30,7 @@
         call. }}
     {{#zcl_struct_items_by_struct_and_cluster_name type cluster}}
       {{#if (hasProperty ../expected label)}}
-        {{>check_test_value actual=(concat "((MTR" (asUpperCamelCase ../cluster) "Cluster" (asUpperCamelCase ../type) " *)" ../actual ")." (asStructPropertyName label)) expected=(lookup ../expected label) cluster=../cluster}}
+        {{>check_test_value actual=(concat "((MTR" (asUpperCamelCase ../cluster preserveAcronyms=true) "Cluster" (asUpperCamelCase ../type preserveAcronyms=true) " *)" ../actual ")." (asStructPropertyName label)) expected=(lookup ../expected label) cluster=../cluster}}
       {{/if}}
     {{/zcl_struct_items_by_struct_and_cluster_name}}
     {{! Maybe we should add a check for properties in the expected object (other

diff --git a/integrations/docker/images/chip-cert-bins/Dockerfile b/integrations/docker/images/chip-cert-bins/Dockerfile
@@ -8,7 +8,7 @@ ARG COMMITHASH=7b99e6399c6069037c613782d78132c69b9dcabb
 # ZAP Development install, so that it runs on both x64 and arm64
 # Generally this should match with the ZAP version that is used for codegen within the
 # specified SHA
-ARG ZAP_VERSION=v2023.07.19-nightly
+ARG ZAP_VERSION=v2023.07.20-nightly
 
 # Ensure TARGETPLATFORM is set
 RUN case ${TARGETPLATFORM} in \

diff --git a/scripts/build/build_darwin_framework.py b/scripts/build/build_darwin_framework.py
@@ -96,6 +96,9 @@ def build_darwin_framework(args):
     for option in options:
         command += ["{}={}".format(option, "YES" if options[option] else "NO")]
 
+    if args.enable_provisional_framework_features:
+        command += ['GCC_PREPROCESSOR_DEFINITIONS=${inherited} MTR_ENABLE_PROVISIONAL=1']
+
     # 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
@@ -171,7 +174,8 @@ def build_darwin_framework(args):
     parser.add_argument('--asan', action=argparse.BooleanOptionalAction)
     parser.add_argument('--ble', action=argparse.BooleanOptionalAction)
     parser.add_argument('--clang', action=argparse.BooleanOptionalAction)
-    parser.add_argument('--enable_encoding_sentinel_enum_values', action=argparse.BooleanOptionalAction)
+    parser.add_argument('--enable-encoding-sentinel-enum-values', action=argparse.BooleanOptionalAction)
+    parser.add_argument('--enable-provisional-framework-features', action=argparse.BooleanOptionalAction)
 
     args = parser.parse_args()
     build_darwin_framework(args)
diff --git a/scripts/setup/zap.json b/scripts/setup/zap.json
@@ -8,13 +8,13 @@
                 "mac-amd64",
                 "windows-amd64"
             ],
-            "tags": ["version:[email protected].19-nightly.1"]
+            "tags": ["version:[email protected].20-nightly.1"]
         },
         {
             "_comment": "Always get the amd64 version on mac until usable arm64 zap build is available",
             "path": "fuchsia/third_party/zap/mac-amd64",
             "platforms": ["mac-arm64"],
-            "tags": ["version:[email protected].19-nightly.1"]
+            "tags": ["version:[email protected].20-nightly.1"]
         }
     ]
 }
diff --git a/scripts/setup/zap.version b/scripts/setup/zap.version
@@ -1 +1 @@
-v2023.07.19-nightly
+v2023.07.20-nightly
diff --git a/scripts/tools/zap/zap_execution.py b/scripts/tools/zap/zap_execution.py
@@ -23,7 +23,7 @@
 # Use scripts/tools/zap/version_update.py to manage ZAP versioning as many
 # files may need updating for versions
 #
-MIN_ZAP_VERSION = '2023.7.19'
+MIN_ZAP_VERSION = '2023.7.20'
 
 
 class ZapTool:

diff --git a/src/darwin/Framework/CHIP/MTRDefines.h b/src/darwin/Framework/CHIP/MTRDefines.h
@@ -53,6 +53,12 @@
 #define MTR_NEWLY_AVAILABLE
 #endif
 
+#if MTR_ENABLE_PROVISIONAL
+#define MTR_PROVISIONALLY_AVAILABLE MTR_NEWLY_AVAILABLE
+#else
+#define MTR_PROVISIONALLY_AVAILABLE NS_UNAVAILABLE MTR_HIDDEN
+#endif
+
 #pragma mark - Types
 
 typedef NSData * MTRTLVBytes;

diff --git a/src/darwin/Framework/CHIP/templates/MTRAttributeTLVValueDecoder-src.zapt b/src/darwin/Framework/CHIP/templates/MTRAttributeTLVValueDecoder-src.zapt
@@ -24,6 +24,9 @@ static id _Nullable DecodeAttributeValueFor{{asUpperCamelCase name preserveAcron
     switch (aAttributeId) {
         {{#zcl_attributes_server removeKeys='isOptional'}}
         {{#if (isSupported (asUpperCamelCase ../name preserveAcronyms=true) attribute=(asUpperCamelCase name preserveAcronyms=true))}}
+        {{#if (isProvisional (asUpperCamelCase ../name preserveAcronyms=true) attribute=(asUpperCamelCase name preserveAcronyms=true))}}
+        #if MTR_ENABLE_PROVISIONAL
+        {{/if}}
         case Attributes::{{asUpperCamelCase name}}::Id: {
             using TypeInfo = Attributes::{{asUpperCamelCase name}}::TypeInfo;
             TypeInfo::DecodableType cppValue;
@@ -36,6 +39,9 @@ static id _Nullable DecodeAttributeValueFor{{asUpperCamelCase name preserveAcron
             {{>decode_value target="value" source="cppValue" cluster=parent.name errorCode="*aError = err; return nil;" depth=0}}
             return value;
         }
+        {{#if (isProvisional (asUpperCamelCase ../name preserveAcronyms=true) attribute=(asUpperCamelCase name preserveAcronyms=true))}}
+        #endif // MTR_ENABLE_PROVISIONAL
+        {{/if}}
         {{/if}}
         {{/zcl_attributes_server}}
         default: {

diff --git a/src/darwin/Framework/CHIP/templates/MTRBaseClusters-src.zapt b/src/darwin/Framework/CHIP/templates/MTRBaseClusters-src.zapt
@@ -256,7 +256,8 @@ reportHandler:(void (^)({{asObjectiveCClass type parent.name}} * _Nullable value
 {{#if (is_str_equal source 'client')}}
 {{! Takes two arguments: cluster name and command name, plus the ambient state where the command is "this" }}
 {{#*inline "commandImpl"}}
-{{#if (isSupported cluster command=command)}}
+{{#if (and (wasIntroducedBeforeRelease "First major API revamp" cluster command=command)
+           (isSupported cluster command=command))}}
 - (void){{asLowerCamelCase command}}WithParams:(MTR{{cluster}}Cluster{{command}}Params * {{#unless commandHasRequiredField}}_Nullable{{/unless}})params completionHandler:({{>command_completion_type command=. compatRemapNames=true}})completionHandler
 {
   [self {{asLowerCamelCase name}}WithParams:params completion: