[ffigen] Add Header Files to CBuilder Sources

pkgs/native_assets_builder/test_data/native_subtract/hook/build.dart

@@ -12,7 +12,10 @@ void main(List<String> arguments) async {
     final cbuilder = CBuilder.library(
       name: packageName,
       assetName: 'src/${packageName}_bindings_generated.dart',
-      sources: ['src/$packageName.c'],
+      sources: [
+        'src/$packageName.c',
+        'src/$packageName.h',
+      ],
     );
     await cbuilder.run(
       input: input,

pkgs/native_assets_cli/README.md

@@ -50,6 +50,23 @@ experiment is only available on the master channel.
 We do breaking changes regularly! So frequently bump `package:native_assets_cli`
 and use dev/master SDK for CI.
 
+**Note:** When configuring `CBuilder` in your `hook/build.dart`, 
+include both `.c` source files and `.h` header files in the `sources` list. 
+This ensures that changes to header files (e.g., `native_add_library.h`) 
+invalidate the build cache, triggering a rebuild when necessary. For example:
+```dart
+final cbuilder = CBuilder.library(
+  name: 'native_add_library',
+  assetName: 'src/native_add_library_bindings_generated.dart',
+  sources: [
+    'src/native_add_library.c',
+    'src/native_add_library.h',
+    'src/dart_api_dl.c',
+    'src/dart_api_dl.h',
+  ],
+);
+```
+
 ## Development
 
 The development of the feature can be tracked in [dart-lang#50565],

pkgs/native_assets_cli/example/build/use_dart_api/hook/build.dart

@@ -12,7 +12,12 @@ void main(List<String> arguments) async {
     final cbuilder = CBuilder.library(
       name: packageName,
       assetName: 'src/${packageName}_bindings_generated.dart',
-      sources: ['src/$packageName.c', 'src/dart_api_dl.c'],
+      sources: [
+        'src/$packageName.c',
+        'src/$packageName.h',
+        'src/dart_api_dl.c',
+        'src/dart_api_dl.h',
+      ],
     );
     await cbuilder.run(
       input: input,

pkgs/native_assets_cli/lib/src/api/build.dart

@@ -31,6 +31,7 @@ import '../validation.dart';
 ///       assetName: '$packageName.dart',
 ///       sources: [
 ///         'src/$packageName.c',
+///         'src/$packageName.h',
 ///       ],
 ///     );
 ///     await cbuilder.run(

pkgs/native_toolchain_c/lib/src/cbuilder/cbuilder.dart

@@ -53,6 +53,24 @@ class CBuilder extends CTool implements Builder {
   CBuilder.library({
     required super.name,
     super.assetName,
+    /// The list of source files to build the library.
+    ///
+    /// This should include both C source files (e.g., `.c`) and header files
+    /// (e.g., `.h`). Including header files ensures that changes to them
+    /// invalidate the build cache, triggering recompilation when necessary.
+    /// For example, for a package named `native_add_library`:
+    /// ```dart
+    /// sources: [
+    ///   'src/native_add_library.c',
+    ///   'src/native_add_library.h',
+    ///   'src/dart_api_dl.c',
+    ///   'src/dart_api_dl.h',
+    /// ],
+    /// ```
+    /// Supported by Clang-like compilers, which can optimize with precompiled
+    /// headers when `.h` files are included. If a compiler does not support this,
+    /// the build system may filter `.h` files from the compilation step while
+    /// still tracking them as dependencies.
     super.sources = const [],
     super.includes = const [],
     super.frameworks = CTool.defaultFrameworks,