LibreSwift iOS Development for VS Code

LibreSwift empowers developers to build, debug, sign, and deploy native iOS Swift applications directly to an iPhone over USB from Linux (and WSL), fully bypassing the need for macOS and Xcode.

Architecture

graph TD
    A[VS Code Extension] --> B[SourceKit-LSP]
    A --> C[xtool]
    A --> D[rcodesign]
    A --> E[libimobiledevice & usbmuxd]
    A --> K[LLDB Remote Debug Bridge]
    A --> L[LibreSwift Doctor]
    
    B --> F{Autocompletion & Diagnostics}
    C --> G(Compile arm64-apple-ios Dynamic Targets)
    D --> H(Sign App Bundle)
    E --> I[Physical iPhone Deployment]
    K --> J[Interactive Breakpoint Debugging]
    L --> M[Environment Diagnostics & Self-Healing]

Features

Getting Started

New users: On first install, LibreSwift automatically opens a guided onboarding walkthrough. Just follow the steps — you can skip at any time and return to it later via Ctrl+Shift+P → Welcome: Open Walkthrough → LibreSwift.

Step 1 — Create a New iOS Project or Open an Existing One

To scaffold a fresh iOS app with all build tasks pre-configured, open the Command Palette (Ctrl+Shift+P) and run:

LibreSwift: Create New iOS Project (SwiftUI / UIKit)

Choose from SwiftUI iOS App, UIKit iOS App, or Swift CLI Tool.

Step 2 — Run the One-Click Setup Engine & Doctor

Open the Command Palette and run:

LibreSwift: One-Click Automated Setup Engine

To verify your system state at any time, run:

LibreSwift: Run Doctor (System Diagnostics)

Step 3 — Extract the iPhoneOS SDK

Download an official Xcode .xip from developer.apple.com (free Apple ID required), then run:

LibreSwift: Setup iOS Environment (Extract SDK)

Step 4 — Configure Code Signing

LibreSwift supports two signing methods:

1. Free Apple ID Signing (Recommended — Zero Mac Required): Run LibreSwift: Configure Apple ID Signing (Free Developer Account) and enter your Apple ID email. LibreSwift generates a local 7-day development certificate and profile automatically.
2. Manual .p12 & Provisioning Profile: In VS Code Settings, set libreswift.p12Path and libreswift.mobileprovisionPath, then run LibreSwift: Set P12 Password.

Step 5 — Connect, Deploy & Debug

1. Plug in your iPhone via USB, unlock it, and trust the computer.
2. Click ▶ Run on iOS in the status bar or 🐞 Debug on Connected iOS Device to start an interactive LLDB debug session.

Windows Subsystem for Linux (WSL)

WSL2 requires USB passthrough via usbipd-win:

# In PowerShell (Admin)
usbipd list
usbipd bind --busid <busid>
usbipd attach --wsl --busid <busid>

Commands

Configuration

Issues & Support

If you encounter bugs, missing toolchains, or unexpected behavior:

1. Run LibreSwift: Run Doctor (System Diagnostics) from the Command Palette (Ctrl+Shift+P).
2. Review the health matrix for any misconfigured SDK paths, broken USB sockets, or missing CLI tools.
3. Open an issue on GitHub: GitHub Issues.
4. Attach the Doctor output log and the relevant section from LibreSwift: Show Device Logs.

Contributing

We welcome contributions from the community! To maintain stability, the repository follows a strict branch lifecycle:

Branching Model

• master — Source of Truth (SoT). Production-ready, stable releases deployed to VS Code Marketplace and Open VSX.
• development — Active development, new features, and integration testing. All pull requests must target development.

Development Workflow

1. Fork the repository and clone it locally.
2. Check out the development branch:

   git checkout development
   

3. Create a feature branch:

   git checkout -b feat/your-feature-name
   

4. Install dependencies and compile:

   npm install
   npm run compile
   

5. Run the test suite:

   node ./out/test/runTest.js
   

6. Commit using Conventional Commits (feat:, fix:, docs:, refactor:, test:).
7. Submit a Pull Request targeting the development branch.

For full guidelines, see CONTRIBUTING.md.

Prerequisites

The following tools are used by LibreSwift. The Setup Engine and Doctor help you install and verify them:

1. xtool — cross-compiler for Swift targeting iOS
2. rcodesign — code signing without macOS
3. libimobiledevice — iOS device communication & syslog streaming
4. usbmuxd — USB daemon for iPhone
5. sourcekit-lsp — Swift language server
6. pbzx, xar, cpio — archive utilities for .xip extraction
7. lldb — debugger for interactive debugging sessions

License

MIT License. See LICENSE for more information.

Acknowledgments

A massive thank you to the developers and maintainers of the open-source tools that make LibreSwift possible:

• The apple-platform-rs team for rcodesign.
• The libimobiledevice community for reverse engineering Apple's protocols.
• The creators of xtool, pbzx, and the Swift open-source community.