diff --git a/work/projects/vscode-migration/tech-design-xcode-build-server.md b/work/projects/vscode-migration/tech-design-xcode-build-server.md index 3f86b8d8..7b905e42 100644 --- a/work/projects/vscode-migration/tech-design-xcode-build-server.md +++ b/work/projects/vscode-migration/tech-design-xcode-build-server.md @@ -8,7 +8,7 @@ ## Background & Requirements - Some of us (would prefer to) spend much of the day outside Xcode: in VS Code, reviewing changes, working with AI agents, or across several worktrees at once. There, the Swift language server has no build information for our Xcode projects. So there's no direct build&run support, no jump to definition, no completion and no errors as you type, and no debugger. -- The [previous tech design](https://app.asana.com/1/137249556945/project/1202406491309510/task/1219304032604521) tried to solve this by making the macOS browser code a Swift package. The team decided not to do it at this stage. The concerns were: +- The [previous tech design](https://app.asana.com/1/137249556945/project/1202406491309510/task/1219304032604521) tried to solve this by making the macOS browser code a Swift package. The team has raised some concerns against doing it at this stage. The concerns were: - a more custom, more fragile setup; - resources that can fail silently at runtime; - no good way to have per-configuration dependencies; @@ -41,14 +41,15 @@ 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. -- The build server is installed locally by a script, from a pinned version. +- 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 the plan is to contribute them upstream. Until they're merged, the repository carries them as a patch that the install script applies. +**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 offer them 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. **Steps** -1. Land the setup in the repository, plus a short README. -2. Open PRs for the build server changes in its repository. -3. A few early adopters on macOS and iOS try it for a couple of weeks; then we decide whether to announce it more widely. +1. Fork sourcekit-xcode-bsp into a DuckDuckGo repository with our changes. +2. Land the setup in the repository, plus a short README. +3. Offer the changes upstream as PRs. +4. A few early adopters on macOS and iOS try it for a couple of weeks; then we decide whether to announce it more widely. ### Pros @@ -60,17 +61,22 @@ Add an opt-in VS Code setup to the repository: a workspace file and a few script ### Cons -- **A young third-party tool** (version 0.1.0, "early-stage" by its authors), and our patch on top of it until upstream accepts the changes. +- **A young third-party tool** (version 0.1.0, "early-stage" by its authors) that we fork and maintain ourselves. - **Some rough edges:** - one platform per worktree at a time; - iOS debugging is two steps (run, then attach); - the first index of a new worktree takes ~5 minutes. - **Someone has to own it.** I will; the setup is small (a workspace file and ~6 scripts), and it's documented. +- **Maintenance as Xcode, swift-build and the build server move.** Xcode updates or upstream changes can need updates to the fork or the setup. Mitigation: the people who use the setup do the updates, mostly with AI agents (the setup is small and has a README and tests). Xcode-only users and CI never depend on it. ### Risks - **Xcode updates can break the build server**, since it bundles its own swift-build. Mitigation: a pinned version and a check after each Xcode update. The worst case is that the setup stops working for the people who opted in; Xcode and CI aren't affected. -- **Upstream doesn't accept the changes** or the project is abandoned. Mitigation: keep a fork under the DuckDuckGo organization (the changes are ~550 lines plus tests), or drop the setup. +- **Malicious code in the build server or its dependencies** (supply chain). It runs on developer machines with access to the source code and the network. Mitigations: + - we build it from source at a pinned commit of our fork; nothing is downloaded prebuilt or updated automatically; + - its own code is small (~1,700 lines in 13 Swift files upstream, plus ~550 lines of our changes), so each upstream update can be reviewed as a diff before it goes into the fork; + - its dependencies come from Apple/swiftlang (swift-build, swift-tools-protocols, swift-argument-parser) and are pinned too. +- **Upstream doesn't accept the changes** or the project is abandoned. Mitigation: the fork already carries our changes, so nothing breaks; we keep it, or drop the setup. - **Xcode and the editor share the index.** Both write to Xcode's index store; deleting the DerivedData folder resets it, as today. ## Testing @@ -86,7 +92,7 @@ Add an opt-in VS Code setup to the repository: a workspace file and a few script ## Additional Considerations -- **Privacy / Security:** No change to the apps. The install script builds the build server from its public repository at a pinned version, and everything runs locally. +- **Privacy / Security:** No change to the apps and no user data involved; the setup only runs locally on developer machines. It does add third-party code to those machines, built from our fork at a pinned commit (see Risks). **Question for reviewers:** does a developer tool like this need a privacy/security triage? It's a small open-source package with Apple-only dependencies, so a light review of the fork may be enough. - **Site Breakage / Experimentation / Localization:** Not applicable. - **Operational:** No CI or release change.