Skip to content

Commit 4e516d7

Browse files
authored
Make Xcode workspace cleaning optional during flutter clean (flutter#190091)
This PR introduces a new `--include-xcode-workspace` flag to flutter clean which makes Xcode workspace cleaning optional, bypassing the expensive xcodebuild execution that inherently triggers Swift Package resolution over the internet. By default, it will now instantly clean local build directories without polling or cleaning Xcode. Additionally, this updates several Xcode-specific error messages across the codebase to explicitly instruct users to run `flutter clean --include-xcode-workspace` when clearing Xcode's derived data is required *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 347dff3 commit 4e516d7

5 files changed

Lines changed: 46 additions & 11 deletions

File tree

‎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: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1264,7 +1264,7 @@ Future<bool> _handleIssues(
12641264
} else if (modifiedPrecompiledSource) {
12651265
logger.printError(
12661266
'════════════════════════════════════════════════════════════════════════════════\n'
1267-
'A precompiled file has been changed since last built. Please run "flutter clean" to clear '
1267+
'A precompiled file has been changed since last built. Please run "flutter clean --include-xcode-workspace" to clear '
12681268
'the cache.\n'
12691269
'════════════════════════════════════════════════════════════════════════════════',
12701270
);
@@ -1532,7 +1532,7 @@ class _XCResultIssueHandlingResult {
15321532
final String? missingModule;
15331533

15341534
/// 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.
1535+
/// changed since last built. This requires "flutter clean --include-xcode-workspace" to resolve.
15361536
final bool modifiedPrecompiledSource;
15371537

15381538
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: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -653,7 +653,7 @@ duplicate symbol '_$s29plugin_1_name23PluginNamePluginC9setDouble3key5valueySS_S
653653
expect(
654654
logger.errorText,
655655
contains(
656-
'A precompiled file has been changed since last built. Please run "flutter clean" to '
656+
'A precompiled file has been changed since last built. Please run "flutter clean --include-xcode-workspace" to '
657657
'clear the cache.',
658658
),
659659
);

0 commit comments

Comments
 (0)