[ffigen] Ignore deprecated APIs (#1403)

Author: liamappelbe

pkgs/ffigen/CHANGELOG.md

@@ -3,6 +3,9 @@
 - Create a public facing API for ffigen that can be invoked as a library:
   `void generate(Config config)`. Make `Config` an implementatble interface,
   rather than needing to be parsed from yaml.
+- Add a `external-versions` config option. Setting the minimum target
+  version will omit APIs from the generated bindings if they were deprecated
+  before this version.
 
 ## 13.0.0
 

pkgs/ffigen/README.md

@@ -662,7 +662,41 @@ import:
     - 'package:some_pkg/symbols.yaml'
     - 'path/to/some/symbol_file.yaml'
 ```
-</td>
+  </td>
+  </tr>
+
+  <tr>
+    <td>
+      external-versions
+    </td>
+    <td>
+      Interfaces, methods, and other API elements may be marked with
+      deprecation annotations that indicate which platform version they were
+      deprecated in. If external-versions is set, APIs that were
+      deprecated as of the minimum version will be omitted from the
+      generated bindings.
+      <br><br>
+      The minimum version is specified per platform, and an API will be
+      generated if it is available on *any* of the targeted platform versions.
+      If a version is not specified for a particular platform, the API's
+      inclusion will be based purely on the platforms that have a specified
+      minimum version.
+      <br><br>
+      Current support OS keys are ios and macos. If you have a use case for
+      version checking on other OSs, please file an issue.
+    </td>
+    <td>
+
+```yaml
+external-versions:
+  # See https://docs.flutter.dev/reference/supported-platforms.
+  ios:
+    min: 12.0.0
+  macos:
+    min: 10.14.0
+```
+
+  </td>
   </tr>
 </tbody>
 </table>

pkgs/ffigen/ffigen.schema.json

@@ -469,6 +469,30 @@
     },
     "silence-enum-warning": {
       "type": "boolean"
+    },
+    "external-versions": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "ios": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "min": {
+              "type": "string"
+            }
+          }
+        },
+        "macos": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "min": {
+              "type": "string"
+            }
+          }
+        }
+      }
     }
   },
   "required": [

pkgs/ffigen/lib/src/config_provider/config.dart

@@ -167,6 +167,10 @@ abstract interface class Config {
   /// Whether to format the output file.
   bool get formatOutput;
 
+  /// Minimum target versions for ObjC APIs, per OS. APIs that were deprecated
+  /// before this version will not be generated.
+  ExternalVersions get externalVersions;
+
   factory Config({
     Uri? filename,
     PackageConfig? packageConfig,
@@ -177,7 +181,7 @@ abstract interface class Config {
     Language language = Language.c,
     required List<Uri> entryPoints,
     bool Function(Uri header)? shouldIncludeHeaderFunc,
-    List<String> compilerOpts = const <String>[],
+    List<String>? compilerOpts,
     Map<String, List<VarArgFunction>> varArgFunctions =
         const <String, List<VarArgFunction>>{},
     DeclarationFilters? functionDecl,
@@ -218,6 +222,7 @@ abstract interface class Config {
     FfiNativeConfig ffiNativeConfig = const FfiNativeConfig(enabled: false),
     bool ignoreSourceErrors = false,
     bool formatOutput = true,
+    ExternalVersions externalVersions = const ExternalVersions(),
   }) =>
       ConfigImpl(
         filename: filename == null ? null : Uri.file(filename.toFilePath()),
@@ -231,7 +236,7 @@ abstract interface class Config {
         language: language,
         entryPoints: entryPoints,
         shouldIncludeHeaderFunc: shouldIncludeHeaderFunc ?? (_) => true,
-        compilerOpts: compilerOpts,
+        compilerOpts: compilerOpts ?? defaultCompilerOpts(),
         varArgFunctions: varArgFunctions,
         functionDecl: functionDecl ?? DeclarationFilters.excludeAll,
         structDecl: structDecl ?? DeclarationFilters.excludeAll,
@@ -286,6 +291,7 @@ abstract interface class Config {
         ffiNativeConfig: ffiNativeConfig,
         ignoreSourceErrors: ignoreSourceErrors,
         formatOutput: formatOutput,
+        externalVersions: externalVersions,
       );
 }
 
@@ -318,4 +324,8 @@ abstract interface class DeclarationFilters {
 
   static final excludeAll = DeclarationFilters();
   static final includeAll = DeclarationFilters(shouldInclude: (_) => true);
+
+  static DeclarationFilters include(Set<String> names) => DeclarationFilters(
+        shouldInclude: (Declaration decl) => names.contains(decl.originalName),
+      );
 }

pkgs/ffigen/lib/src/config_provider/config_impl.dart

@@ -172,6 +172,9 @@ class ConfigImpl implements Config {
   @override
   final bool formatOutput;
 
+  @override
+  final ExternalVersions externalVersions;
+
   ConfigImpl({
     required this.filename,
     required this.packageConfig,
@@ -222,6 +225,7 @@ class ConfigImpl implements Config {
     required this.ffiNativeConfig,
     required this.ignoreSourceErrors,
     required this.formatOutput,
+    required this.externalVersions,
   });
 }
 

pkgs/ffigen/lib/src/config_provider/config_types.dart

@@ -7,6 +7,7 @@ library;
 
 import 'dart:io';
 
+import 'package:pub_semver/pub_semver.dart';
 import 'package:quiver/pattern.dart' as quiver;
 
 import '../code_generator.dart';
@@ -432,3 +433,19 @@ class Declaration {
     required this.originalName,
   });
 }
+
+class ExternalVersions {
+  final Versions? ios;
+  final Versions? macos;
+  const ExternalVersions({this.ios, this.macos});
+}
+
+class Versions {
+  final Version? min;
+
+  // TODO(https://github.com/dart-lang/native/issues/300): max isn't supported
+  // yet.
+  final Version? max;
+
+  const Versions({this.min, this.max});
+}

pkgs/ffigen/lib/src/config_provider/spec_utils.dart

@@ -9,6 +9,7 @@ import 'package:glob/glob.dart';
 import 'package:logging/logging.dart';
 import 'package:package_config/package_config.dart';
 import 'package:path/path.dart' as p;
+import 'package:pub_semver/pub_semver.dart';
 import 'package:quiver/pattern.dart' as quiver;
 import 'package:yaml/yaml.dart';
 
@@ -631,3 +632,23 @@ FfiNativeConfig ffiNativeExtractor(dynamic yamlConfig) {
     assetId: yamlMap?[strings.ffiNativeAsset] as String?,
   );
 }
+
+ExternalVersions externalVersionsExtractor(Map<dynamic, dynamic>? yamlConfig) =>
+    ExternalVersions(
+      ios: versionsExtractor(yamlConfig?[strings.ios]),
+      macos: versionsExtractor(yamlConfig?[strings.macos]),
+    );
+
+Versions? versionsExtractor(dynamic yamlConfig) {
+  final yamlMap = yamlConfig as Map?;
+  if (yamlMap == null) return null;
+  return Versions(
+    min: versionExtractor(yamlMap[strings.externalVersionsMin]),
+  );
+}
+
+Version? versionExtractor(dynamic yamlVersion) {
+  final versionString = yamlVersion as String?;
+  if (versionString == null) return null;
+  return Version.parse(versionString);
+}

pkgs/ffigen/lib/src/config_provider/yaml_config.dart

@@ -284,6 +284,12 @@ class YamlConfig implements Config {
   @override
   bool formatOutput = true;
 
+  /// Minimum target versions for ObjC APIs, per OS. APIs that were deprecated
+  /// before this version will not be generated.
+  @override
+  ExternalVersions get externalVersions => _externalVersions;
+  late ExternalVersions _externalVersions;
+
   YamlConfig._({required this.filename, required this.packageConfig});
 
   /// Create config from Yaml map.
@@ -828,6 +834,28 @@ class YamlConfig implements Config {
           defaultValue: (node) => false,
           resultOrDefault: (node) => _silenceEnumWarning = node.value as bool,
         ),
+        HeterogeneousMapEntry(
+          key: strings.externalVersions,
+          valueConfigSpec: HeterogeneousMapConfigSpec(
+            entries: strings.externalVersionsPlatforms
+                .map((plat) => HeterogeneousMapEntry(
+                      key: plat,
+                      valueConfigSpec: HeterogeneousMapConfigSpec(
+                        entries: [
+                          HeterogeneousMapEntry(
+                            key: strings.externalVersionsMin,
+                            valueConfigSpec: StringConfigSpec(),
+                          ),
+                        ],
+                      ),
+                    ))
+                .toList(),
+            transform: (node) => externalVersionsExtractor(node.value),
+          ),
+          defaultValue: (node) => const ExternalVersions(),
+          resultOrDefault: (node) =>
+              _externalVersions = (node.value) as ExternalVersions,
+        ),
       ],
     );
   }