[ffigen] Fix usrTypeMappings field of Config factory constructor

pkgs/ffigen/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 18.0.0-dev
+
+- Add variable substitutions that can be used in the `headers.entry-points` to
+  locate Apple APIs: `$XCODE`, `$IOS_SDK`, and `$MACOS_SDK`.
+- __Breaking change__: Change the `usrTypeMappings` field of `Config`'s factory
+  constructor from a `List<ImportedType>` to a `Map<String, ImportedType>`.
+
 ## 17.0.0
 
 - Use package:objective_c 6.0.0

pkgs/ffigen/README.md

@@ -1139,3 +1139,25 @@ The property filtering rules live in the same `objc-interfaces.member-filter`
 option as the methods. There is no distinction between methods and properties in
 the filters. The protocol filtering rules live in
 `objc-protocols.member-filter`.
+
+### How do I generate bindings for Apple APIs?
+
+It can be tricky to locate header files containing Apple's ObjC frameworks, and
+the paths can vary between computers depending on which version of Xcode you are
+using and where it is installed. So ffigen provides the following variable
+substitutions that can be used in the `headers.entry-points` list:
+
+- `$XCODE`: Replaced with the result of `xcode-select -p`, which is the
+  directory where Xcode's APIs are installed.
+- `$IOS_SDK`: Replaced with `xcrun --show-sdk-path --sdk iphoneos`, which is the
+  directory within `$XCODE` where the iOS SDK is installed.
+- `$MACOS_SDK`: Replaced with `xcrun --show-sdk-path --sdk macosx`, which is the
+  directory within `$XCODE` where the macOS SDK is installed.
+
+For example:
+
+```Yaml
+headers:
+  entry-points:
+    - '$MACOS_SDK/System/Library/Frameworks/Foundation.framework/Headers/NSDate.h'
+```

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

@@ -224,7 +224,7 @@ abstract interface class Config {
     bool sort = false,
     bool useSupportedTypedefs = true,
     List<LibraryImport> libraryImports = const <LibraryImport>[],
-    List<ImportedType> usrTypeMappings = const <ImportedType>[],
+    Map<String, ImportedType> usrTypeMappings = const <String, ImportedType>{},
     List<ImportedType> typedefTypeMappings = const <ImportedType>[],
     List<ImportedType> structTypeMappings = const <ImportedType>[],
     List<ImportedType> unionTypeMappings = const <ImportedType>[],
@@ -285,9 +285,7 @@ abstract interface class Config {
         libraryImports: Map<String, LibraryImport>.fromEntries(
             libraryImports.map((import) =>
                 MapEntry<String, LibraryImport>(import.name, import))),
-        usrTypeMappings: Map<String, ImportedType>.fromEntries(
-            usrTypeMappings.map((import) =>
-                MapEntry<String, ImportedType>(import.nativeType, import))),
+        usrTypeMappings: usrTypeMappings,
         typedefTypeMappings: Map<String, ImportedType>.fromEntries(
             typedefTypeMappings.map((import) =>
                 MapEntry<String, ImportedType>(import.nativeType, import))),

pkgs/ffigen/pubspec.yaml

@@ -3,7 +3,7 @@
 # BSD-style license that can be found in the LICENSE file.
 
 name: ffigen
-version: 17.0.0
+version: 18.0.0-dev
 description: >
   Generator for FFI bindings, using LibClang to parse C, Objective-C, and Swift
   files.