[ffigen] add example from readme as real example for reference (#2697)

Author: goderbauer

.github/workflows/ffigen.yml

@@ -37,7 +37,7 @@ jobs:
           channel: 'stable'
       - id: install
         name: Install dependencies
-        run: flutter pub get && flutter pub get --directory="example/shared_bindings" && flutter pub get --directory="../objective_c"
+        run: flutter pub get && flutter pub get --directory="example/shared_bindings" && flutter pub get --directory="../objective_c" && flutter pub get --directory="example/add"
       - name: Check formatting
         run: dart format --output=none --set-exit-if-changed .
         if: always() && steps.install.outcome == 'success'

pkgs/ffigen/README.md

@@ -117,6 +117,8 @@ app has been created via `dart create ffigen_example`.
 
 That's it! Run your app with `dart run` to see it in action!
 
+The complete and runnable example can be found in [example/add](example/add).
+
 ## More Examples
 
 The `code_asset` package contains [comprehensive examples](../code_assets/example)

pkgs/ffigen/example/README.md

@@ -1,7 +1,20 @@
 ## Examples
 
-- [Simple](https://github.com/dart-lang/native/tree/main/pkgs/ffigen/example/simple)
-- [cJSON](https://github.com/dart-lang/native/tree/main/pkgs/ffigen/example/c_json)
-- [LibClang](https://github.com/dart-lang/native/tree/main/pkgs/ffigen/example/libclang-example)
-- [ObjectiveC](https://github.com/dart-lang/native/tree/main/pkgs/ffigen/example/objective_c)
-- [Swift](https://github.com/dart-lang/native/tree/main/pkgs/ffigen/example/swift)
+- [Add](add): Simple end-to-end example from FFIgen's [README.md](../README.md)
+  that shows how FFIgen can be used to call a custom C API from a Dart app.
+- [package:code_assets examples](../../code_assets/example): Various end-to-end
+  examples showcasing how FFIgen can be used in real world scenarios.
+- [Simple](simple): Very simple example that generates bindigns for a very small
+  header file.
+- [cJSON](c_json): Demonstrates generation of bindings for a C library 
+  ([cJson](https://github.com/DaveGamble/cJSON)).
+- [LibClang](libclang-example): Demonstrates generating bindings for 
+  [Libclang](https://clang.llvm.org/doxygen/group__CINDEX.html).
+- [ObjectiveC](objective_c): Showcases how to generate bindings for an
+  Objective-C library.
+- [Swift](swift): Demonstrates how to use FFIgen to interact with Swift
+  libraries.
+- [FFINative](ffinative): Example for generating `Native` bindings for a very
+  small header file.
+- [SharedBindings](shared_bindings): Showcases how bindings can share types with
+  other bindings.

pkgs/ffigen/example/add/README.md

@@ -0,0 +1,10 @@
+A simple end-to-end example using FFIgen.
+
+FFIgen bindings are generated by the script in `tool/ffigen.dart`. Execute
+`dart run tool/ffigen.dart` to regenerate the bindings.
+
+The C source files for which bindings are generated are located in `src/`.
+
+The bindings are imported and used by `lib/add.dart`.
+
+To run the app and see it in action execute `dart run`.

pkgs/ffigen/example/add/bin/add.dart

@@ -0,0 +1,9 @@
+// Copyright (c) 2025, 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.
+
+import 'package:add/add.dart' as add;
+
+void main(List<String> arguments) {
+  add.answerToLife();
+}

pkgs/ffigen/example/add/hook/build.dart

@@ -0,0 +1,16 @@
+import 'package:code_assets/code_assets.dart';
+import 'package:hooks/hooks.dart';
+import 'package:native_toolchain_c/native_toolchain_c.dart';
+
+void main(List<String> args) async {
+  await build(args, (input, output) async {
+    if (input.config.buildCodeAssets) {
+      final builder = CBuilder.library(
+        name: 'add',
+        assetName: 'add.g.dart',
+        sources: ['src/add.c'],
+      );
+      await builder.run(input: input, output: output);
+    }
+  });
+}

pkgs/ffigen/example/add/lib/add.dart

@@ -0,0 +1,9 @@
+// Copyright (c) 2025, 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.
+
+import 'add.g.dart';
+
+void answerToLife() {
+  print('The answer to the Ultimate Question is ${add(40, 2)}!');
+}

pkgs/ffigen/example/add/lib/add.g.dart

@@ -0,0 +1,8 @@
+// AUTO GENERATED FILE, DO NOT EDIT.
+//
+// Generated by `package:ffigen`.
+// ignore_for_file: type=lint
+import 'dart:ffi' as ffi;
+
+@ffi.Native<ffi.Int Function(ffi.Int, ffi.Int)>()
+external int add(int a, int b);

pkgs/ffigen/example/add/pubspec.yaml

@@ -0,0 +1,17 @@
+name: add
+description: A simple end-to-end example showcasing FFIgen.
+publish_to: none
+
+environment:
+  sdk: '>=3.8.0 <4.0.0'
+
+dependencies:
+  code_assets: any
+  ffi: ^2.1.4
+  hooks: any
+  native_toolchain_c: any
+
+dev_dependencies:
+  ffigen:
+    path: '../../'
+  test: ^1.25.15

pkgs/ffigen/example/add/src/add.c

@@ -0,0 +1,7 @@
+// Copyright (c) 2025, 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.
+
+int add(int a, int b) {
+  return a + b;
+}