Symbol file import export

.github/workflows/test-package.yml

@@ -27,7 +27,7 @@ jobs:
           sdk: ${{ matrix.sdk }}
       - id: install
         name: Install dependencies
-        run: dart pub get
+        run: dart pub get && dart pub get --directory="example/shared_bindings"
       - name: Check formatting
         run: dart format --output=none --set-exit-if-changed .
         if: always() && steps.install.outcome == 'success'

CHANGELOG.md

@@ -1,3 +1,7 @@
+# 7.2.0
+- Added support for sharing bindings using `symbol-file` config. (See `README.md`
+and examples/shared_bindings).
+
 # 7.1.0
 - Handle declarations with definition accessible from a different entry-point.
 

README.md

@@ -91,6 +91,12 @@ The following configuration options are available-
 
 ```yaml
 output: 'generated_bindings.dart'
+```
+or
+```yaml
+output:
+  bindings: 'generated_bindings.dart'
+  ... 
 ```
   </td>
   </tr>
@@ -521,6 +527,36 @@ language: 'objc'
 ```
   </td>
   </tr>
+  <tr>
+    <td>output -> symbol-file</td>
+    <td>Generates a symbol file yaml containing all types defined in the generated output.</td>
+    <td>
+
+```yaml
+output:
+  ...
+  symbol-file:
+    # Although file paths are supported here, prefer Package Uri's here
+    # so that other pacakges can use them.
+    output: 'package:some_pkg/symbols.yaml'
+    import-path: 'package:some_pkg/base.dart'
+```
+</td>
+  </tr>
+  <tr>
+    <td>import -> symbol-files</td>
+    <td>Import symbols from a symbol file. Used for sharing type definitions from other pacakges.</td>
+    <td>
+
+```yaml
+import:
+  symbol-files:
+    # Both package Uri and file paths are supported here.
+    - 'package:some_pkg/symbols.yaml'
+    - 'path/to/some/symbol_file.yaml'
+```
+</td>
+  </tr>
 </tbody>
 </table>
 
@@ -757,3 +793,16 @@ Ffigen can sometimes generate a lot of logs, especially when it's parsing a lot
     Level options are - `[all, fine, info (default), warning, severe]`.
     The `all` and `fine` will print a ton of logs are meant for debugging
     purposes only.
+
+### How can type definitions be shared?
+
+Ffigen can share type definitions using symbol files.
+- A package can generate a symbol file using the `output -> symbol-file` config.
+- And another package can then import this, using `import -> symbol-files` config.
+- Doing so will reuse all the types such as Struct/Unions, and will automatically
+ exclude generating other types (E.g functions, enums, macros).
+
+Checkout `examples/shared_bindings` for details.
+
+For manually reusing definitions from another package, the `library-imports`
+and `type-map` config can be used.

example/shared_bindings/.gitignore

@@ -0,0 +1,11 @@
+# Files and directories created by pub.
+.dart_tool/
+.packages
+# Remove the following pattern if you wish to check in your lock file.
+pubspec.lock
+
+# Conventional directory for build outputs.
+build/
+
+# Directory created by dartdoc.
+doc/api/

example/shared_bindings/README.md

@@ -0,0 +1,10 @@
+# Shared bindings
+
+An example to showcase how bindings can share types
+with other bindings.
+
+## Generating bindings
+At the root of this example (`example/shared_bindings`), run -
+```
+dart run generate.dart
+```

example/shared_bindings/ffigen_configs/a.yaml

@@ -0,0 +1,12 @@
+# Copyright (c) 2022, the Dart project authors. Please see the AUTHORS file
+# for details. All rights reserved. Use of this source code is governed by a
+# BSD-style license that can be found in the LICENSE file.
+
+name: NativeLibraryA
+description: Bindings to `headers/a.h`.
+output: '../lib/generated/a_gen.dart'
+headers:
+  entry-points:
+    - '../headers/a.h'
+preamble: |
+  // ignore_for_file: non_constant_identifier_names, camel_case_types

example/shared_bindings/ffigen_configs/a_shared_base.yaml

@@ -0,0 +1,16 @@
+# Copyright (c) 2022, the Dart project authors. Please see the AUTHORS file
+# for details. All rights reserved. Use of this source code is governed by a
+# BSD-style license that can be found in the LICENSE file.
+
+name: NativeLibraryASharedB
+description: Bindings to `headers/a.h` with shared definitions from `headers/base.h`.
+output: '../lib/generated/a_shared_b_gen.dart'
+headers:
+  entry-points:
+    - '../headers/a.h'
+import:
+  symbol-files:
+    # Both package Uri and file paths are supported here.
+    - 'package:shared_bindings/generated/base_symbols.yaml'
+preamble: |
+  // ignore_for_file: non_constant_identifier_names, camel_case_types

example/shared_bindings/ffigen_configs/base.yaml

@@ -0,0 +1,17 @@
+# Copyright (c) 2022, the Dart project authors. Please see the AUTHORS file
+# for details. All rights reserved. Use of this source code is governed by a
+# BSD-style license that can be found in the LICENSE file.
+
+name: NativeLibraryBase
+description: Bindings to `headers/base.h`.
+output:
+  bindings: '../lib/generated/base_gen.dart'
+  symbol-file:
+    # Although file paths are supported here, prefer Package Uri's here.
+    output: 'package:shared_bindings/generated/base_symbols.yaml'
+    import-path: 'package:shared_bindings/generated/base_gen.dart'
+headers:
+  entry-points:
+    - '../headers/base.h'
+preamble: |
+  // ignore_for_file: non_constant_identifier_names, camel_case_types

example/shared_bindings/generate.dart

@@ -0,0 +1,32 @@
+import 'dart:io';
+
+import 'package:cli_util/cli_util.dart';
+import 'package:path/path.dart' as p;
+
+ProcessResult runFfigenForConfig(String sdkPath, String configPath) {
+  return Process.runSync(
+    p.join(sdkPath, 'bin', 'dart'),
+    [
+      'run',
+      'ffigen',
+      '--config=$configPath',
+    ],
+    runInShell: Platform.isWindows,
+  );
+}
+
+void main() {
+  final sdkPath = getSdkPath();
+  final configPaths = [
+    'ffigen_configs/base.yaml',
+    'ffigen_configs/a.yaml',
+    'ffigen_configs/a_shared_base.yaml'
+  ];
+  for (final configPath in configPaths) {
+    final res = runFfigenForConfig(sdkPath, configPath);
+    print(res.stdout.toString());
+    if (res.exitCode != 0) {
+      throw Exception("Some error occurred: ${res.stderr.toString()}");
+    }
+  }
+}

example/shared_bindings/headers/a.h

@@ -0,0 +1,21 @@
+
+#include "base.h"
+
+struct A_Struct1{
+    int a;
+};
+
+union A_Union1{
+    int a;
+};
+
+enum A_Enum{
+    A_ENUM_1,
+    A_ENUM_2,
+};
+
+#define A_MACRO_1 1;
+
+void a_func1();
+
+void a_func2(struct BaseStruct2 s, union BaseUnion2 u, BaseTypedef2 t);

example/shared_bindings/headers/base.h

@@ -0,0 +1,31 @@
+// Copyright (c) 2022, the Dart project authors. Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+struct BaseStruct1{
+    int a;
+};
+
+union BaseUnion1{
+    int a;
+};
+
+struct BaseStruct2{
+    int a;
+};
+
+union BaseUnion2{
+    int a;
+};
+
+typedef struct BaseStruct1 BaseTypedef1;
+typedef struct BaseStruct2 BaseTypedef2;
+
+enum BaseEnum{
+    BASE_ENUM_1,
+    BASE_ENUM_2,
+};
+
+#define BASE_MACRO_1 1;
+
+void base_func1(BaseTypedef1 t1, BaseTypedef2 t2);

example/shared_bindings/lib/generated/a_gen.dart

@@ -0,0 +1,112 @@
+// ignore_for_file: non_constant_identifier_names, camel_case_types
+
+// AUTO GENERATED FILE, DO NOT EDIT.
+//
+// Generated by `package:ffigen`.
+import 'dart:ffi' as ffi;
+
+/// Bindings to `headers/a.h`.
+class NativeLibraryA {
+  /// Holds the symbol lookup function.
+  final ffi.Pointer<T> Function<T extends ffi.NativeType>(String symbolName)
+      _lookup;
+
+  /// The symbols are looked up in [dynamicLibrary].
+  NativeLibraryA(ffi.DynamicLibrary dynamicLibrary)
+      : _lookup = dynamicLibrary.lookup;
+
+  /// The symbols are looked up with [lookup].
+  NativeLibraryA.fromLookup(
+      ffi.Pointer<T> Function<T extends ffi.NativeType>(String symbolName)
+          lookup)
+      : _lookup = lookup;
+
+  void base_func1(
+    BaseTypedef1 t1,
+    BaseTypedef2 t2,
+  ) {
+    return _base_func1(
+      t1,
+      t2,
+    );
+  }
+
+  late final _base_func1Ptr = _lookup<
+          ffi.NativeFunction<ffi.Void Function(BaseTypedef1, BaseTypedef2)>>(
+      'base_func1');
+  late final _base_func1 =
+      _base_func1Ptr.asFunction<void Function(BaseTypedef1, BaseTypedef2)>();
+
+  void a_func1() {
+    return _a_func1();
+  }
+
+  late final _a_func1Ptr =
+      _lookup<ffi.NativeFunction<ffi.Void Function()>>('a_func1');
+  late final _a_func1 = _a_func1Ptr.asFunction<void Function()>();
+
+  void a_func2(
+    BaseStruct2 s,
+    BaseUnion2 u,
+    BaseTypedef2 t,
+  ) {
+    return _a_func2(
+      s,
+      u,
+      t,
+    );
+  }
+
+  late final _a_func2Ptr = _lookup<
+      ffi.NativeFunction<
+          ffi.Void Function(BaseStruct2, BaseUnion2, BaseTypedef2)>>('a_func2');
+  late final _a_func2 = _a_func2Ptr
+      .asFunction<void Function(BaseStruct2, BaseUnion2, BaseTypedef2)>();
+}
+
+class BaseStruct1 extends ffi.Struct {
+  @ffi.Int()
+  external int a;
+}
+
+class BaseUnion1 extends ffi.Union {
+  @ffi.Int()
+  external int a;
+}
+
+class BaseStruct2 extends ffi.Struct {
+  @ffi.Int()
+  external int a;
+}
+
+class BaseUnion2 extends ffi.Union {
+  @ffi.Int()
+  external int a;
+}
+
+abstract class BaseEnum {
+  static const int BASE_ENUM_1 = 0;
+  static const int BASE_ENUM_2 = 1;
+}
+
+typedef BaseTypedef1 = BaseStruct1;
+typedef BaseTypedef2 = BaseStruct2;
+
+class A_Struct1 extends ffi.Struct {
+  @ffi.Int()
+  external int a;
+}
+
+class A_Union1 extends ffi.Union {
+  @ffi.Int()
+  external int a;
+}
+
+abstract class A_Enum {
+  static const int A_ENUM_1 = 0;
+  static const int A_ENUM_2 = 1;
+}
+
+const int BASE_MACRO_1 = 1;
+
+const int A_MACRO_1 = 1;