[native_toolchain_c] Forced includes (#2096)

Author: zeyus

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

@@ -55,6 +55,7 @@ class CBuilder extends CTool implements Builder {
     super.assetName,
     super.sources = const [],
     super.includes = const [],
+    super.forcedIncludes = const [],
     super.frameworks = CTool.defaultFrameworks,
     super.libraries = const [],
     super.libraryDirectories = CTool.defaultLibraryDirectories,
@@ -81,6 +82,7 @@ class CBuilder extends CTool implements Builder {
     required super.name,
     super.sources = const [],
     super.includes = const [],
+    super.forcedIncludes = const [],
     super.frameworks = CTool.defaultFrameworks,
     super.libraries = const [],
     super.libraryDirectories = CTool.defaultLibraryDirectories,
@@ -149,6 +151,10 @@ class CBuilder extends CTool implements Builder {
       for (final directory in this.includes)
         packageRoot.resolveUri(Uri.file(directory)),
     ];
+    final forcedIncludes = [
+      for (final file in this.forcedIncludes)
+        packageRoot.resolveUri(Uri.file(file)),
+    ];
     final dartBuildFiles = [
       // ignore: deprecated_member_use_from_same_package
       for (final source in this.dartBuildFiles) packageRoot.resolve(source),
@@ -164,6 +170,7 @@ class CBuilder extends CTool implements Builder {
       logger: logger,
       sources: sources,
       includes: includes,
+      forcedIncludes: forcedIncludes,
       frameworks: frameworks,
       libraries: libraries,
       libraryDirectories: libraryDirectories,
@@ -220,6 +227,7 @@ class CBuilder extends CTool implements Builder {
       // Note: We use a Set here to deduplicate the dependencies.
       ...sources,
       ...includeFiles,
+      ...forcedIncludes,
       ...dartBuildFiles,
     });
   }

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

@@ -28,6 +28,7 @@ class CLinker extends CTool implements Linker {
     required this.linkerOptions,
     super.sources = const [],
     super.includes = const [],
+    super.forcedIncludes = const [],
     super.frameworks = CTool.defaultFrameworks,
     super.libraries = const [],
     super.libraryDirectories = CTool.defaultLibraryDirectories,

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

@@ -46,6 +46,18 @@ abstract class CTool {
   /// The sources will be reported as dependencies of the hook.
   final List<String> includes;
 
+  /// Files passed to the compiler that will be included before all source
+  /// files.
+  ///
+  /// Resolved against [LinkInput.packageRoot].
+  ///
+  /// The sources will be reported as dependencies of the hook.
+  /// For clang, each of the files are added as an `-include` flag.
+  /// see: https://gcc.gnu.org/onlinedocs/gcc-13.2.0/gcc/Preprocessor-Options.html#index-include
+  /// For MSVC, each of the files are added as an `/FI` flag.
+  /// see: https://learn.microsoft.com/en-us/cpp/build/reference/fi-name-forced-include-file
+  final List<String> forcedIncludes;
+
   /// Frameworks to link.
   ///
   /// Only effective if [language] is [Language.objectiveC].
@@ -154,6 +166,7 @@ abstract class CTool {
     required this.assetName,
     required this.sources,
     required this.includes,
+    required this.forcedIncludes,
     required this.frameworks,
     required this.libraries,
     required this.libraryDirectories,

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

@@ -26,6 +26,7 @@ class RunCBuilder {
   final Logger? logger;
   final List<Uri> sources;
   final List<Uri> includes;
+  final List<Uri> forcedIncludes;
   final List<String> frameworks;
   final List<String> libraries;
   final List<Uri> libraryDirectories;
@@ -56,6 +57,7 @@ class RunCBuilder {
     this.logger,
     this.sources = const [],
     this.includes = const [],
+    this.forcedIncludes = const [],
     required this.frameworks,
     this.libraries = const [],
     this.libraryDirectories = const [],
@@ -301,6 +303,8 @@ class RunCBuilder {
         for (final MapEntry(key: name, :value) in defines.entries)
           if (value == null) '-D$name' else '-D$name=$value',
         for (final include in includes) '-I${include.toFilePath()}',
+        for (final forcedInclude in forcedIncludes)
+          '-include${forcedInclude.toFilePath()}',
         ...sourceFiles,
         if (language == Language.objectiveC) ...[
           for (final framework in frameworks) ...['-framework', framework],
@@ -359,6 +363,8 @@ class RunCBuilder {
         for (final MapEntry(key: name, :value) in defines.entries)
           if (value == null) '/D$name' else '/D$name=$value',
         for (final directory in includes) '/I${directory.toFilePath()}',
+        for (final forcedInclude in forcedIncludes)
+          '/FI${forcedInclude.toFilePath()}',
         if (executable != null) ...[
           ...sources.map((e) => e.toFilePath()),
           '/link',

pkgs/native_toolchain_c/test/cbuilder/cbuilder_test.dart

@@ -233,6 +233,9 @@ void main() {
     if (!await File.fromUri(definesCUri).exists()) {
       throw Exception('Run the test from the root directory.');
     }
+    final forcedIncludeCUri = packageUri.resolve(
+      'test/cbuilder/testfiles/defines/src/forcedInclude.c',
+    );
     const name = 'defines';
 
     final logMessages = <String>[];
@@ -268,6 +271,7 @@ void main() {
     final cbuilder = CBuilder.executable(
       name: name,
       sources: [definesCUri.toFilePath()],
+      forcedIncludes: [forcedIncludeCUri.toFilePath()],
       flags: [flag],
       buildMode: BuildMode.release,
     );
@@ -278,6 +282,8 @@ void main() {
     final result = await runProcess(executable: executableUri, logger: logger);
     expect(result.exitCode, 0);
     expect(result.stdout, contains('Macro FOO is defined: USER_FLAG'));
+    // Check the forced include is added.
+    expect(result.stdout, contains('Macro FIFOO is defined: "QuotedFIFOO"'));
 
     final compilerInvocation = logMessages.singleWhere(
       (message) => message.contains(definesCUri.toFilePath()),

pkgs/native_toolchain_c/test/cbuilder/testfiles/defines/src/defines.c

@@ -34,5 +34,11 @@ int main() {
   MACRO_IS_UNDEFINED(FOO);
 #endif
 
+#ifdef FIFOO
+  MACRO_IS_DEFINED(FIFOO);
+#else
+  MACRO_IS_UNDEFINED(FIFOO);
+#endif
+
   return 0;
 }

pkgs/native_toolchain_c/test/cbuilder/testfiles/defines/src/forcedInclude.c

@@ -0,0 +1,3 @@
+#ifndef FIFOO
+#define FIFOO "QuotedFIFOO"
+#endif