[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/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

@@ -17,6 +17,25 @@ import 'output_type.dart';
 import 'run_cbuilder.dart';
 
 /// Specification for building an artifact with a C compiler.
+///
+/// **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',
+///   ],
+/// );
+/// ```
+///
+/// This class provides options to define sources, dependencies,
+/// and compiler configurations for building C-based native libraries.
 class CBuilder extends CTool implements Builder {
   /// The dart files involved in building this artifact.
   ///

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

@@ -37,6 +37,13 @@ abstract class CTool {
   /// Resolved against [LinkInput.packageRoot].
   ///
   /// The sources will be reported as dependencies of the hook.
+  ///
+  /// 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.
+  ///
+  /// If a compiler does not support this, the build system may filter `.h` files
+  /// from the compilation step while still tracking them as dependencies.
   final List<String> sources;
 
   /// Include directories to pass to the linker.