[2026-10-15] eagle: work/projects/vscode-migration/tech-design-xcode-build-server.md

work/projects/vscode-migration/tech-design-xcode-build-server.md

@@ -27,7 +27,8 @@ Code autocompletion, jump-to-definition and debugging in VS Code and Cursor need
 
 ## Recommended Approach
 
-Add an opt-in VS Code setup to the repository: a workspace file and a few scripts in `scripts/vscode/`. Nothing else in the repository changes.
+- Add an opt-in VS Code setup to the repository: a workspace file and a few scripts in `scripts/vscode/`. This design doesn't change anything Xcode uses: the projects, schemes, xcconfigs and CI stay as they are. 
+- Buildable folders, mentioned below, is separate task.
 
 **What a developer gets**
 - Completion, jump-to-definition, references and live errors for app, test and package code, on macOS or iOS. One platform is chosen per worktree and can be switched.
@@ -40,6 +41,7 @@ Add an opt-in VS Code setup to the repository: a workspace file and a few script
 **How it works**
 - The workspace generates the build server's config on folder open. The config chooses the platform and the targets to index, the same way an Xcode scheme does.
 - Builds and tests go through `xcodebuild` with the same settings Xcode uses.
+- Works with the projects as they are, including buildable folders, which are being adopted separately (agreed in the [previous tech design's discussion](https://app.asana.com/1/137249556945/task/1219304032604521/comment/1219461135882510?focus=true)). With them, adding a file in VS Code needs no project edits, which completes the editor workflow.
 - The build server is installed locally by a script that builds it from source at a pinned commit of our fork (see below).
 
 **The build server needed fixes.** On our workspace it gave no results in test files, broke on the DMG/App Store variants and took hours to index. Four small changes fix this (see Appendix), and a worktree now indexes in about 5 minutes. They're general improvements, so we'll open a PR for the upstream. We don't depend on upstream accepting them: we fork the build server into a DuckDuckGo repository, keep our changes there and pull upstream changes manually after reviewing them.
@@ -79,18 +81,14 @@ Add an opt-in VS Code setup to the repository: a workspace file and a few script
 - **The setup breaks Xcode builds or the Xcode setup.** Mitigation: it changes nothing Xcode uses. The projects, schemes, xcconfigs, `Package.resolved` files and CI stay as they are. The setup only adds a workspace file and scripts, and VS Code builds run `xcodebuild` on the same projects with Xcode's settings.
 - **A file added from VS Code works there but is missing in Xcode.** New files have to be added to the Xcode project, which is easy to forget outside Xcode. Mitigations:
   - VS Code builds use the same projects and `xcodebuild` configuration as Xcode, so a file missing from a target fails the VS Code build too; the editor also shows no code intelligence for it;
-  - adopting buildable folders, which is already in progress, removes the need to edit `project.pbxproj` for new files.
+  - adopting buildable folders, removes the need to edit `project.pbxproj` for new files.
 
 ## Testing
 
-- Code intelligence: macOS and iOS app files, app unit tests (including jumping into app code), package tests.
-- Tasks:
-  - building macOS and iOS schemes;
-  - running unit tests;
-  - builds from Xcode and VS Code don't rebuild each other's work.
-- Debugging: breakpoints in the macOS app and in the iOS app on a simulator.
+- VSCode compatibility: macOS and iOS app files, app tests, jumping into app and packages code, package tests.
+- CI run validates nothing is broken in the existing setup.
 - The build server changes have unit tests.
-- Before documenting it for the team: two people try it on fresh machines in VS Code and Cursor, and we check that Xcode picks up a worktree built and indexed from VS Code without rebuilding.
+- Before documenting it for the team: two people try it on fresh machines in VS Code, and we check that Xcode picks up a worktree built and indexed from VS Code without rebuilding.
 
 ## Additional Considerations