Add LLDB warnings (#170827)

LLDB is now required again for iOS 26+ so add back warnings.

## Pre-launch Checklist

- [x] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [x] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [x] I read and followed the [Flutter Style Guide], including [Features
we expect every widget to implement].
- [x] I signed the [CLA].
- [ ] I listed at least one issue that this PR fixes in the description
above.
- [x] I updated/added relevant documentation (doc comments with `///`).
- [x] I added new tests to check the change I am making, or this PR is
[test-exempt].
- [x] I followed the [breaking change policy] and added [Data Driven
Fixes] where supported.
- [x] All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel
on [Discord].

<!-- Links -->
[Contributor Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview
[Tree Hygiene]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md
[test-exempt]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests
[Flutter Style Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md
[Features we expect every widget to implement]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement
[CLA]: https://cla.developers.google.com/
[flutter/tests]: https://github.com/flutter/tests
[breaking change policy]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes
[Discord]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md
[Data Driven Fixes]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md

Author: vashworth

dev/devicelab/bin/tasks/build_ios_framework_module_test.dart

@@ -451,14 +451,6 @@ Future<void> _testBuildIosFramework(Directory projectDir, {bool isModule = false
     throw TaskResult.failure('Unexpected GeneratedPluginRegistrant.m.');
   }
 
-  if (File(path.join(outputPath, 'flutter_lldbinit')).existsSync() == isModule) {
-    throw TaskResult.failure('Unexpected flutter_lldbinit');
-  }
-
-  if (File(path.join(outputPath, 'flutter_lldb_helper.py')).existsSync() == isModule) {
-    throw TaskResult.failure('Unexpected flutter_lldb_helper.py.');
-  }
-
   section('Build frameworks without plugins');
   await _testBuildFrameworksWithoutPlugins(projectDir, platform: 'ios');
 

packages/flutter_tools/lib/src/build_system/targets/darwin.dart

@@ -7,6 +7,7 @@ import 'package:meta/meta.dart';
 import '../../artifacts.dart';
 import '../../base/io.dart';
 import '../../build_info.dart';
+import '../../globals.dart' as globals show stdio;
 import '../build_system.dart';
 
 abstract class UnpackDarwin extends Target {
@@ -111,3 +112,63 @@ abstract class UnpackDarwin extends Target {
     }
   }
 }
+
+/// Log warning message to the Xcode build logs. Log will show as yellow with an icon.
+///
+/// If the issue occurs in a specific file, include the [filePath] as an absolute path.
+/// If the issue occurs at a specific line in the file, include the [lineNumber] as well.
+/// The [filePath] and [lineNumber] are optional.
+void printXcodeWarning(String warning, {String? filePath, int? lineNumber}) {
+  _printXcodeLog(XcodeLogType.warning, warning, filePath: filePath, lineNumber: lineNumber);
+}
+
+/// Log error message to the Xcode build logs. Log will show as red with an icon and may cause the build to fail.
+///
+/// If the issue occurs in a specific file, include the [filePath] as an absolute path.
+/// If the issue occurs at a specific line in the file, include the [lineNumber] as well.
+/// The [filePath] and [lineNumber] are optional.
+void printXcodeError(String error, {String? filePath, int? lineNumber}) {
+  _printXcodeLog(XcodeLogType.error, error, filePath: filePath, lineNumber: lineNumber);
+}
+
+/// Log note message to the Xcode build logs. Log will show with no special color or icon.
+///
+/// If the issue occurs in a specific file, include the [filePath] as an absolute path.
+/// If the issue occurs at a specific line in the file, include the [lineNumber] as well.
+/// The [filePath] and [lineNumber] are optional.
+void printXcodeNote(String note, {String? filePath, int? lineNumber}) {
+  _printXcodeLog(XcodeLogType.note, note, filePath: filePath, lineNumber: lineNumber);
+}
+
+/// Log [message] to the Xcode build logs.
+///
+/// If [logType] is [XcodeLogType.error], log will show as red with an icon and may cause the build to fail.
+/// If [logType] is [XcodeLogType.warning], log will show as yellow with an icon.
+/// If [logType] is [XcodeLogType.note], log will show with no special color or icon.
+///
+///
+/// If the issue occurs in a specific file, include the [filePath] as an absolute path.
+/// If the issue occurs at a specific line in the file, include the [lineNumber] as well.
+/// The [filePath] and [lineNumber] are optional.
+///
+/// See Apple's documentation:
+/// https://developer.apple.com/documentation/xcode/running-custom-scripts-during-a-build#Log-errors-and-warnings-from-your-script
+void _printXcodeLog(XcodeLogType logType, String message, {String? filePath, int? lineNumber}) {
+  String linePath = '';
+  if (filePath != null) {
+    linePath = '$filePath:';
+
+    // A line number is meaningless without a filePath, so only set if filePath is also provided.
+    if (lineNumber != null) {
+      linePath = '$linePath$lineNumber:';
+    }
+  }
+  if (linePath.isNotEmpty) {
+    linePath = '$linePath ';
+  }
+
+  // Must be printed to stderr to be streamed to the Flutter tool in xcode_backend.dart.
+  globals.stdio.stderrWrite('$linePath${logType.name}: $message\n');
+}
+
+enum XcodeLogType { error, warning, note }

packages/flutter_tools/lib/src/build_system/targets/ios.dart

@@ -12,6 +12,7 @@ import '../../base/file_system.dart';
 import '../../base/io.dart';
 import '../../base/logger.dart' show Logger;
 import '../../base/process.dart';
+import '../../base/version.dart';
 import '../../build_info.dart';
 import '../../darwin/darwin.dart';
 import '../../devfs.dart';
@@ -486,6 +487,113 @@ class _IssueLaunchRootViewControllerAccess extends Target {
   List<Source> get outputs => <Source>[];
 }
 
+/// This target verifies that the Xcode project has an LLDB Init File set within
+/// at least one scheme.
+///
+/// LLDB Init File is needed for debugging on physical iOS 26+ devices.
+class DebugIosLLDBInit extends Target {
+  const DebugIosLLDBInit();
+
+  @override
+  String get name => 'debug_ios_lldb_init';
+
+  @override
+  List<Source> get inputs => const <Source>[
+    Source.pattern('{FLUTTER_ROOT}/packages/flutter_tools/lib/src/build_system/targets/ios.dart'),
+    Source.pattern(
+      '{FLUTTER_ROOT}/packages/flutter_tools/lib/src/build_system/targets/darwin.dart',
+    ),
+  ];
+
+  @override
+  List<Source> get outputs => <Source>[
+    Source.fromProject((FlutterProject project) => project.ios.lldbInitFile),
+  ];
+
+  @override
+  List<Target> get dependencies => <Target>[];
+
+  @override
+  Future<void> build(Environment environment) async {
+    final String? sdkRoot = environment.defines[kSdkRoot];
+    if (sdkRoot == null) {
+      throw MissingDefineException(kSdkRoot, name);
+    }
+    final EnvironmentType? environmentType = environmentTypeFromSdkroot(
+      sdkRoot,
+      environment.fileSystem,
+    );
+
+    // LLDB Init File is only required for physical devices in debug mode.
+    if (environmentType != EnvironmentType.physical) {
+      return;
+    }
+
+    final String? targetDeviceVersionString = environment.defines[kTargetDeviceOSVersion];
+    if (targetDeviceVersionString == null) {
+      // Skip if TARGET_DEVICE_OS_VERSION is not found. TARGET_DEVICE_OS_VERSION
+      // is not set if "build ios-framework" is called, which builds the
+      // DebugIosApplicationBundle directly rather than through flutter assemble.
+      // If may also be null if the build is targeting multiple architectures.
+      return;
+    }
+
+    final Version? targetDeviceVersion = Version.parse(targetDeviceVersionString);
+    if (targetDeviceVersion == null) {
+      environment.logger.printError(
+        'Failed to parse TARGET_DEVICE_OS_VERSION: $targetDeviceVersionString',
+      );
+      return;
+    }
+
+    // LLDB Init File is only needed for iOS 26+.
+    if (targetDeviceVersion < Version(26, 0, null)) {
+      return;
+    }
+
+    final String? srcRoot = environment.defines[kSrcRoot];
+    if (srcRoot == null) {
+      environment.logger.printError('Failed to find $srcRoot');
+      return;
+    }
+
+    final Directory xcodeProjectDir = environment.fileSystem.directory(srcRoot);
+    if (!xcodeProjectDir.existsSync()) {
+      environment.logger.printError('Failed to find ${xcodeProjectDir.path}');
+      return;
+    }
+
+    // The scheme name is not available in Xcode Build Phases Run Scripts.
+    // Instead, find all xcscheme files in the Xcode project (this may be the
+    // Flutter Xcode project or an Add to App native Xcode project) and check
+    // if any of them contain "customLLDBInitFile". If none have it set, print
+    // a warning.
+    // Also, this cannot check for a specific path/name for the LLDB Init File
+    // since Flutter's LLDB Init file may be imported from within a user's
+    // custom LLDB Init File.
+    bool anyLLDBInitFound = false;
+    await for (final FileSystemEntity entity in xcodeProjectDir.list(recursive: true)) {
+      if (environment.fileSystem.path.extension(entity.path) == '.xcscheme' && entity is File) {
+        if (entity.readAsStringSync().contains('customLLDBInitFile')) {
+          anyLLDBInitFound = true;
+          break;
+        }
+      }
+    }
+    if (!anyLLDBInitFound) {
+      final FlutterProject flutterProject = FlutterProject.fromDirectory(environment.projectDir);
+      final String tab = flutterProject.isModule ? 'Use CocoaPods' : 'Use frameworks';
+      printXcodeWarning(
+        'Debugging Flutter on new iOS versions requires an LLDB Init File. To '
+        'ensure debug mode works, please complete instructions found in '
+        '"Embed a Flutter module in your iOS app > $tab > Set LLDB Init File" '
+        'section of https://docs.flutter.dev/to/ios-add-to-app-embed-setup.',
+      );
+    }
+    return;
+  }
+}
+
 /// The base class for all iOS bundle targets.
 ///
 /// This is responsible for setting up the basic App.framework structure, including:
@@ -641,7 +749,11 @@ class DebugIosApplicationBundle extends IosAssetBundle {
   ];
 
   @override
-  List<Target> get dependencies => <Target>[const DebugUniversalFramework(), ...super.dependencies];
+  List<Target> get dependencies => <Target>[
+    const DebugUniversalFramework(),
+    const DebugIosLLDBInit(),
+    ...super.dependencies,
+  ];
 }
 
 /// IosAssetBundle with debug symbols, used for Profile and Release builds.

packages/flutter_tools/lib/src/commands/build_ios_framework.dart

@@ -374,12 +374,22 @@ class BuildIOSFrameworkCommand extends BuildFrameworkCommand {
       );
     }
 
-    if (!project.isModule && buildInfos.any((BuildInfo info) => info.isDebug)) {
+    if (buildInfos.any((BuildInfo info) => info.isDebug)) {
       // Add-to-App must manually add the LLDB Init File to their native Xcode
       // project, so provide the files and instructions.
       final File lldbInitSourceFile = project.ios.lldbInitFile;
       final File lldbInitTargetFile = outputDirectory.childFile(lldbInitSourceFile.basename);
       final File lldbHelperPythonFile = project.ios.lldbHelperPythonFile;
+
+      if (!lldbInitTargetFile.existsSync()) {
+        // If LLDB is being added to the output, print a warning with instructions on how to add.
+        globals.printWarning(
+          'Debugging Flutter on new iOS versions requires an LLDB Init File. To '
+          'ensure debug mode works, please complete instructions found in '
+          '"Embed a Flutter module in your iOS app > Use frameworks > Set LLDB Init File" '
+          'section of https://docs.flutter.dev/to/ios-add-to-app-embed-setup.',
+        );
+      }
       lldbInitSourceFile.copySync(lldbInitTargetFile.path);
       lldbHelperPythonFile.copySync(outputDirectory.childFile(lldbHelperPythonFile.basename).path);
     }

packages/flutter_tools/lib/src/xcode_project.dart

@@ -774,20 +774,6 @@ def __lldb_init_module(debugger: lldb.SBDebugger, _):
   Future<void> _updateLLDBIfNeeded() async {
     if (globals.cache.isOlderThanToolsStamp(lldbInitFile) ||
         globals.cache.isOlderThanToolsStamp(lldbHelperPythonFile)) {
-      if (isModule) {
-        // When building a module project for Add-to-App, provide instructions
-        // to manually add the LLDB Init File to their native Xcode project.
-        globals.logger.printWarning(
-          'Debugging Flutter on new iOS versions requires an LLDB Init File. '
-          'To ensure debug mode works, please complete one of the following in '
-          'your native Xcode project:\n'
-          '  * Open Xcode > Product > Scheme > Edit Scheme. For both the Run and Test actions, set LLDB Init File to: \n\n'
-          '    ${lldbInitFile.path}\n\n'
-          '  * If you are already using an LLDB Init File, please append the '
-          'following to your LLDB Init File:\n\n'
-          '    command source ${lldbInitFile.path}\n',
-        );
-      }
       await _renderTemplateToFile(_lldbInitTemplate, null, lldbInitFile, globals.templateRenderer);
       await _renderTemplateToFile(
         _lldbPythonHelperTemplate,