Skip to content
This repository was archived by the owner on Aug 15, 2026. It is now read-only.

Commit 39e450c

Browse files
authored
Reland "Make Xcode workspace cleaning optional during flutter clean" (flutter#191023)
The original [PR](flutter#190091) skipped cleaning Xcode's `DerivedData` Clang module cache by default. This caused the `plugin_lint_mac` test to fail because the test dynamically toggles `use_frameworks!` off and expects a clean slate. Since `DerivedData` wasn't wiped, Xcode's cached index expected the previously generated `.framework/Modules/module.modulemap` to exist in `build/` (which `flutter clean` had just deleted), resulting in a `module map file not found` build failure. To fix this, the `--include-xcode-workspace` flag is now added to the test. Since toggling `use_frameworks!` isn't a general use case , there is now an actionable error to gracefully guide developers to run `flutter clean --include-xcode-workspace` if they hit this cache corruption. *List which issues are fixed by this PR. You must list at least one issue. An issue is not required if the PR fixes something trivial like a typo.* Fixes flutter#183946, flutter#173940 and flutter#127708 too *If you had to change anything in the [flutter/tests] repo, include a link to the migration guide as per the [breaking change policy].* ## Pre-launch Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I read the [AI contribution guidelines] and understand my responsibilities, or I am not using AI tools. - [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]. - [x] I listed at least one issue that this PR fixes in the description above. - [ ] I updated/added relevant documentation (doc comments with `///`). - [ ] I added new tests to check the change I am making, or this PR is [test-exempt]. - [ ] 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]. If this change needs to override an active code freeze, provide a comment explaining why. The code freeze workflow can be overridden by code reviewers. See pinned issues for any active code freezes with guidance. **Note**: The Flutter team is currently trialing the use of [Gemini Code Assist for GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code). Comments from the `gemini-code-assist` bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed. <!-- Links --> [Contributor Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview [AI contribution guidelines]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#ai-contribution-guidelines [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
1 parent f6b5d1f commit 39e450c

6 files changed

Lines changed: 96 additions & 22 deletions

File tree

‎dev/devicelab/bin/tasks/plugin_lint_mac.dart‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -183,7 +183,7 @@ Future<void> main() async {
183183
pluginPubspec.writeAsStringSync(pluginPubspecContent, flush: true);
184184

185185
await inDirectory(appPath, () async {
186-
await flutter('clean');
186+
await flutter('clean', options: <String>['--include-xcode-workspace']);
187187
await flutter('build', options: <String>['ios', '--no-codesign']);
188188
});
189189

‎packages/flutter_tools/lib/src/commands/clean.dart‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,13 @@ class CleanCommand extends FlutterCommand {
2929
'Also clean the example directory, if one exists. '
3030
'Useful when developing in a package project.',
3131
);
32+
argParser.addFlag(
33+
'include-xcode-workspace',
34+
negatable: false,
35+
help:
36+
'Whether to run "xcodebuild clean" on the Xcode workspace for iOS and macOS projects. '
37+
"This removes build products and intermediate files from Xcode's build cache and can be slow to complete.",
38+
);
3239
argParser.addFlag(
3340
'stop-gradle',
3441
negatable: false,
@@ -56,7 +63,10 @@ class CleanCommand extends FlutterCommand {
5663
Future<FlutterCommandResult> runCommand() async {
5764
final FlutterProject flutterProject = FlutterProject.current();
5865
final Xcode? xcode = globals.xcode;
59-
final bool cleanXcode = xcode != null && xcode.isInstalledAndMeetsVersionCheck;
66+
final bool userWantsXcodeClean =
67+
boolArg('include-xcode-workspace') || (argResults?.wasParsed('scheme') ?? false);
68+
final bool cleanXcode =
69+
xcode != null && xcode.isInstalledAndMeetsVersionCheck && userWantsXcodeClean;
6070

6171
await _cleanProject(flutterProject, cleanXcode: cleanXcode);
6272
if (boolArg('include-example')) {

‎packages/flutter_tools/lib/src/ios/mac.dart‎

Lines changed: 10 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1084,16 +1084,14 @@ _XCResultIssueHandlingResult _handleXCResultIssue({
10841084
hasProvisioningProfileIssue: false,
10851085
duplicateModule: duplicateModule,
10861086
);
1087-
} else if (message.toLowerCase().contains('not found')) {
1088-
final String? missingModule = _parseMissingModule(message);
1089-
if (missingModule != null) {
1090-
return _XCResultIssueHandlingResult(
1091-
requiresProvisioningProfile: false,
1092-
hasProvisioningProfileIssue: false,
1093-
missingModule: missingModule,
1094-
);
1095-
}
1096-
} else if (message.toLowerCase().contains('has been modified since')) {
1087+
} else if (message.toLowerCase().contains('not found') && _parseMissingModule(message) != null) {
1088+
return _XCResultIssueHandlingResult(
1089+
requiresProvisioningProfile: false,
1090+
hasProvisioningProfileIssue: false,
1091+
missingModule: _parseMissingModule(message),
1092+
);
1093+
} else if (message.toLowerCase().contains('has been modified since') ||
1094+
(message.toLowerCase().contains('module map file') && message.toLowerCase().contains('not found'))) {
10971095
return _XCResultIssueHandlingResult(
10981096
requiresProvisioningProfile: false,
10991097
hasProvisioningProfileIssue: false,
@@ -1264,7 +1262,7 @@ Future<bool> _handleIssues(
12641262
} else if (modifiedPrecompiledSource) {
12651263
logger.printError(
12661264
'════════════════════════════════════════════════════════════════════════════════\n'
1267-
'A precompiled file has been changed since last built. Please run "flutter clean" to clear '
1265+
'A precompiled file has been changed since last built. Please run "flutter clean --include-xcode-workspace" to clear '
12681266
'the cache.\n'
12691267
'════════════════════════════════════════════════════════════════════════════════',
12701268
);
@@ -1532,7 +1530,7 @@ class _XCResultIssueHandlingResult {
15321530
final String? missingModule;
15331531

15341532
/// An issue indicates that a source file, such as a header in the Flutter framework, has
1535-
/// changed since last built. This requires "flutter clean" to resolve.
1533+
/// changed since last built. This requires "flutter clean --include-xcode-workspace" to resolve.
15361534
final bool modifiedPrecompiledSource;
15371535

15381536
final bool unableToFindArmDestination;

‎packages/flutter_tools/lib/src/macos/swift_package_manager.dart‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -236,7 +236,7 @@ class SwiftPackageManager {
236236
/// If a symlink already exists and points to the correct target, creation is skipped
237237
/// to avoid potential Xcode parallel target build race conditions.
238238
/// If creation fails due to sharing violations or locks (e.g., when Xcode is open),
239-
/// throws a descriptive [ToolExit] advising the user to close Xcode and run "flutter clean".
239+
/// throws a descriptive [ToolExit] advising the user to close Xcode and run "flutter clean --include-xcode-workspace".
240240
void _createPluginSymlink({required Link pluginSymlink, required String packagePath}) {
241241
final FileSystemEntityType type = _fileSystem.typeSync(pluginSymlink.path, followLinks: false);
242242
var skipCreation = false;
@@ -277,7 +277,7 @@ class SwiftPackageManager {
277277
throwToolExit(
278278
'Failed to create Swift Package plugin symlink at "${pluginSymlink.path}" to "$packagePath":\n'
279279
'$e\n'
280-
'If Xcode is currently open, please close Xcode, run "flutter clean", and try building again.',
280+
'If Xcode is currently open, please close Xcode, run "flutter clean --include-xcode-workspace", and try building again.',
281281
);
282282
}
283283
}

‎packages/flutter_tools/test/commands.shard/hermetic/clean_test.dart‎

Lines changed: 30 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ void main() {
5959
xcodeProjectInterpreter.isInstalled = true;
6060
xcodeProjectInterpreter.version = Version(1000, 0, 0);
6161
final CommandRunner<void> runner = createTestCommandRunner(CleanCommand());
62-
await runner.run(<String>['clean']);
62+
await runner.run(<String>['clean', '--include-xcode-workspace']);
6363

6464
expect(buildDirectory, isNot(exists));
6565
expect(projectUnderTest.dartTool, isNot(exists));
@@ -102,6 +102,31 @@ void main() {
102102
},
103103
);
104104

105+
testUsingContext(
106+
'$CleanCommand does not clean Xcode by default',
107+
() async {
108+
final FlutterProject projectUnderTest = setupProjectUnderTest(fs.currentDirectory, true);
109+
xcodeProjectInterpreter.isInstalled = true;
110+
xcodeProjectInterpreter.version = Version(1000, 0, 0);
111+
final CommandRunner<void> runner = createTestCommandRunner(CleanCommand());
112+
await runner.run(<String>['clean']);
113+
114+
expect(buildDirectory, isNot(exists));
115+
expect(projectUnderTest.dartTool, isNot(exists));
116+
expect(projectUnderTest.android.ephemeralDirectory, isNot(exists));
117+
expect(projectUnderTest.ios.ephemeralDirectory, isNot(exists));
118+
119+
// The workspaces should be empty since we didn't pass --include-xcode-workspace.
120+
expect(xcodeProjectInterpreter.workspaces, isEmpty);
121+
},
122+
overrides: <Type, Generator>{
123+
FileSystem: () => fs,
124+
ProcessManager: () => FakeProcessManager.any(),
125+
Xcode: () => xcode,
126+
XcodeProjectInterpreter: () => xcodeProjectInterpreter,
127+
},
128+
);
129+
105130
testUsingContext(
106131
'$CleanCommand does not clean the example directory by default',
107132
() async {
@@ -116,7 +141,7 @@ void main() {
116141
xcodeProjectInterpreter.isInstalled = true;
117142
xcodeProjectInterpreter.version = Version(1000, 0, 0);
118143
final CommandRunner<void> runner = createTestCommandRunner(CleanCommand());
119-
await runner.run(<String>['clean']);
144+
await runner.run(<String>['clean', '--include-xcode-workspace']);
120145

121146
expect(buildDirectory, isNot(exists));
122147

@@ -159,7 +184,7 @@ void main() {
159184
xcodeProjectInterpreter.version = Version(1000, 0, 0);
160185

161186
final CommandRunner<void> runner = createTestCommandRunner(CleanCommand());
162-
await runner.run(<String>['clean', '--include-example']);
187+
await runner.run(<String>['clean', '--include-example', '--include-xcode-workspace']);
163188

164189
expect(buildDirectory, isNot(exists));
165190
expect(projectUnderTest.dartTool, isNot(exists));
@@ -209,7 +234,7 @@ void main() {
209234
xcodeProjectInterpreter.isInstalled = true;
210235
xcodeProjectInterpreter.version = Version(1000, 0, 0);
211236
final CommandRunner<void> runner = createTestCommandRunner(CleanCommand());
212-
await runner.run(<String>['clean', '--include-example']);
237+
await runner.run(<String>['clean', '--include-example', '--include-xcode-workspace']);
213238

214239
expect(testLogger.statusText, contains('No example app found'));
215240
},
@@ -302,7 +327,7 @@ void main() {
302327

303328
final command = CleanCommand(verbose: true);
304329
final CommandRunner<void> runner = createTestCommandRunner(command);
305-
await runner.run(<String>['clean']);
330+
await runner.run(<String>['clean', '--include-xcode-workspace']);
306331

307332
expect(xcodeProjectInterpreter.workspaces, const <CleanWorkspaceCall>[
308333
CleanWorkspaceCall('/ios/Runner.xcworkspace', 'Runner', true),

‎packages/flutter_tools/test/general.shard/ios/mac_test.dart‎

Lines changed: 42 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -609,6 +609,47 @@ duplicate symbol '_$s29plugin_1_name23PluginNamePluginC9setDouble3key5valueySS_S
609609
},
610610
);
611611

612+
testWithoutContext('parses missing module map error', () async {
613+
const buildCommands = <String>['xcrun', 'cc', 'blah'];
614+
final buildResult = XcodeBuildResult(
615+
success: false,
616+
stdout: '',
617+
xcodeBuildExecution: XcodeBuildExecution(
618+
buildCommands: buildCommands,
619+
appDirectory: '/blah/blah',
620+
environmentType: EnvironmentType.physical,
621+
buildSettings: buildSettings,
622+
),
623+
xcResult: XCResult.test(
624+
issues: <XCResultIssue>[
625+
XCResultIssue.test(
626+
message:
627+
"module map file '.../test_app/build/ios/Release-iphoneos/url_launcher_ios/url_launcher_ios.framework/Modules/module.modulemap' not found",
628+
subType: 'Error',
629+
),
630+
],
631+
),
632+
);
633+
final fs = MemoryFileSystem.test();
634+
final project = FakeFlutterProject(fileSystem: fs, usesSwiftPackageManager: true);
635+
project.ios.podfile.createSync(recursive: true);
636+
await diagnoseXcodeBuildFailure(
637+
buildResult,
638+
logger: logger,
639+
analytics: fakeAnalytics,
640+
fileSystem: fs,
641+
platform: FlutterDarwinPlatform.ios,
642+
project: project,
643+
);
644+
expect(
645+
logger.errorText,
646+
contains(
647+
'A precompiled file has been changed since last built. Please run "flutter clean --include-xcode-workspace" to '
648+
'clear the cache.',
649+
),
650+
);
651+
});
652+
612653
testWithoutContext('parses file has been modified error', () async {
613654
const buildCommands = <String>['xcrun', 'cc', 'blah'];
614655
final buildResult = XcodeBuildResult(
@@ -653,7 +694,7 @@ duplicate symbol '_$s29plugin_1_name23PluginNamePluginC9setDouble3key5valueySS_S
653694
expect(
654695
logger.errorText,
655696
contains(
656-
'A precompiled file has been changed since last built. Please run "flutter clean" to '
697+
'A precompiled file has been changed since last built. Please run "flutter clean --include-xcode-workspace" to '
657698
'clear the cache.',
658699
),
659700
);

0 commit comments

Comments
 (0)