Skip to content
View kxbuild's full-sized avatar

Block or report kxbuild

Block user

Prevent this user from interacting with your repositories and sending you notifications. Learn more about blocking users.

You must be logged in to block users.

Content in all repositories owned by your account will be closed.
Maximum 250 characters. Please don’t include any personal information such as legal names or email addresses. This note will only be visible to you.
Report abuse

Contact GitHub support about this user’s behavior. Learn more about reporting abuse.

Report abuse
kxbuild/README.md
kxbuild

kxbuild

English · 简体中文

Build iOS apps from the command line on Windows, Linux and macOS

kxbuild is a build system for Xcode projects, in the role xcodebuild plays on a Mac.
It reads .xcodeproj / .xcworkspace / Package.swift as they are, accepts xcodebuild's own command-line syntax,
and produces signed .ipa files ready for the App Store. Runs on Windows, Linux and macOS. No Xcode required.


Windows Linux macOS

Install · Project types · VS Code extension · Issues

✨ Highlights

🖥️ Cross-platform Builds natively on Windows, Linux and macOS
📂 No project changes Build settings, schemes, target dependencies and compiler flags are read by Xcode's rules
🔧 xcodebuild compatible Ships drop-in xcodebuild, xcrun and codesign, so framework build scripts run unchanged
🔏 Signing built in Drop your .p12 and .mobileprovision into a keychain folder and every build signs automatically
📦 One command to .ipa A Release build writes an App Store-ready .ipa, including SwiftSupport
📱 Install on device --install builds, signs and installs on a USB-connected iPhone in one step
🤖 Script and CI friendly --json prints one JSON event per line, and exit codes follow the usual 0 / non-zero rule
✍️ Any editor Use it from a terminal, a CI pipeline, or whichever editor you like. Nothing to configure in the project

🖥️ Supported Platforms

OS Version Build Sign Install on iPhone
Windows Windows 10 / 11 (WSL recommended) ✅ ✅ ✅
Linux Major distros / WSL ✅ ✅ ✅
macOS macOS ✅ ✅ ✅

🧱 Supported Project Types

Each guide shows how to prepare and build that kind of project with the kxbuild command line.

Project type Guide
Swift / SwiftUI / UIKit and Swift packages doc/en/swift.md
Objective-C (and mixed Objective-C / Swift) doc/en/objective-c.md
CocoaPods doc/en/cocoapods.md
Flutter doc/en/flutter.md
React Native doc/en/react-native.md
Expo doc/en/expo.md
🟢 uni-app (HBuilderX) doc/en/uni-app.md
Kotlin Multiplatform / Compose doc/en/kotlin-multiplatform.md
Unity (exported Xcode project) doc/en/unity.md
Godot (exported Xcode project) doc/en/godot.md
Cocos Creator / cocos2d-x doc/en/cocos2d-x.md
🔌 Dev server over USB (Metro, livereload, any framework) doc/en/dev-server.md
Cordova doc/en/cordova.md

C and C++ sources inside any of these projects build as part of the project.

🧩 VS Code Extension

The KXBuild extension brings the same builds into VS Code: press F5 to build, sign, install on the iPhone and stop at your breakpoints. It adds code completion before the first build, visual editors for Info.plist, String Catalogs, asset catalogs and project settings, and React Native Fast Refresh. It works on Windows, Linux and macOS.

Press F5: the app starts on the iPhone, a tap stops it at a breakpoint in VS Code

Install it in either of these ways:

  • VS Code: paste vscode:extension/kxbuild.kxbuild into your browser's address bar to open the extension page in VS Code, or search for KXBuild in the Extensions view (Ctrl+Shift+X) and click Install.
  • Cursor, Windsurf, VSCodium and other editors that use Open VSX: install it from open-vsx.org/extension/kxbuild/kxbuild, or search for KXBuild in the editor's Extensions view.

Features, screenshots, command-line usage and AI prompts are in doc/en/vscode.md.

🤖 AI Coding Agents

Claude Code, GitHub Copilot, Cursor, Codex and Windsurf can build the app, run it on your iPhone, read its logs, take screenshots, tap through the screens, debug with breakpoints and publish to App Store Connect: kxbuild mcp and kxdevice mcp are MCP servers, every command has --json, new projects carry an AGENTS.md, and kxstore skill --install user teaches the agent the App Store commands (upload, metadata, screenshots, review, TestFlight). Setup for each agent is in doc/en/ai-agents.md.

📥 Install

kxbuild is currently in private beta. Sign up to join the waitlist, and we'll email you when your access is ready. ⭐ Star or 👀 Watch this repo (top right) to get notified of updates.

Run the command for your OS and follow the prompts.

Linux / macOS / WSL

curl -fsSL https://www.kxbuild.net/install.sh | bash

Windows (PowerShell)

irm https://www.kxbuild.net/install.ps1 | iex
  • The default install directory is ~/kxbuild (%USERPROFILE%\kxbuild on Windows). The installer asks first, so you can enter another absolute path. It sets KXBUILD_HOME and adds its bin folder to PATH.
  • On Windows, installing inside WSL (Ubuntu) is recommended. A native Windows install also sets up the Visual Studio C++ Build Tools (10–20 GB), and Windows' 260-character path limit can break builds of deeply nested projects.

Then open a new terminal and check the environment. You're ready when every check passes.

kxbuild doctor

To update later, run kxbuild doctor again. It installs the newest kxbuild, then updates the SDKs and components.

⌨️ Quick Start

1. Create a project (skip this for an existing project)

kxbuild project create -t app_swiftui -n MyApp -b com.example.myapp -o D:\projects

kxbuild project templates lists all templates: SwiftUI, UIKit, Objective-C, CocoaPods, Flutter, React Native, Expo, frameworks and static libraries.

2. Set up signing

Put your .p12 certificate and .mobileprovision profile in a keychain folder in the project root, with a password.properties file. See Signing.

3. Build and install on your iPhone

Connect the iPhone over USB, tap Trust This Computer, and turn on Developer Mode (Settings → Privacy & Security → Developer Mode). Then:

kxbuild build D:\projects\MyApp\MyApp.xcodeproj --install

4. Build an App Store .ipa

Put your Apple Distribution certificate (.p12) and the app's App Store provisioning profile in the project's keychain folder, then:

kxbuild build D:\projects\MyApp\MyApp.xcodeproj -c Release --export app-store

The package is written to build\MyApp.ipa in the project folder. Upload it to App Store Connect with kxstore (kxstore build upload build\MyApp.ipa); TestFlight and App Review work as usual.

🛠️ kxbuild Commands

Command What it does
kxbuild doctor [project] Updates kxbuild and its components, then checks and fixes the build environment. With a project path, also prepares that project (Flutter, React Native, Expo, Kotlin Multiplatform, Cocos Creator and cocos2d-x need this before their first build)
kxbuild build <project> Compiles, links, signs and packages an .xcodeproj, .xcworkspace or Package.swift folder, optionally installing it on a device
kxbuild run <project> Builds the app, installs it on the connected iPhone and launches it; optionally collects its logs, a screenshot and its view hierarchy
kxbuild test <project> Builds a scheme's tests and runs them on a connected iOS 17+ device (XCTest and Swift Testing)
kxbuild project resolve <project> Resolves Swift package dependencies
kxbuild project … Inspects, creates, edits and converts Xcode projects: info, templates, create, settings, add-setting, add-package, add-target, add-folder, add-resource, localization, spm2app, to-spm
kxbuild license … Shows the license state, starts a trial or activates this computer: status, trial, activate, refresh, deactivate
kxbuild mcp MCP server for AI coding agents, see doc/en/ai-agents.md
kxbuild version Prints version information
kxstore … App Store Connect from the command line: login with an API key, cert / profile / device / bundle, build upload, metadata, screenshot, review submit, testflight, iap, pricing, or everything as one kxstore release; see doc/en/ai-agents.md

Every command accepts --help for its full list of options.

kxbuild build options

kxbuild build <project.xcodeproj|project.xcworkspace|package dir> [flags]
Option Description
-s, --scheme NAME / -t, --target NAME Scheme or target to build. Without either, the default scheme is built
-c, --config NAME Build configuration. Defaults to the scheme's, else Debug
--sdk NAME, --arch ARCH, --toolchain NAME SDK (iphoneos, iphonesimulator, macosx), architecture and toolchain
-D, --setting KEY=VALUE Overrides a build setting. Repeatable; same precedence as xcodebuild KEY=VALUE
--xcconfig PATH Applies an .xcconfig file, like xcodebuild -xcconfig
-o, --ipa PATH / --no-ipa Where to write the .ipa, or skip packaging
--export app-store Signs with an Apple Distribution certificate and an App Store profile from keychain, for an .ipa to upload to App Store Connect (also ad-hoc, enterprise, development)
-i, --install Installs the signed app on the connected iPhone after a successful build
--derivedDataDir DIR, --clean Build output root (default ~/DerivedData), and empty it before building
--ignoreDependence Builds only the named targets, skipping their dependencies
-j, --jobs N, --explain, --timing, -v, --verbose, --no-cache Parallelism and diagnostics
--emit-commands-only Writes only compile_commands.json for editor code completion; nothing is compiled
--skip-package-updates, --only-use-versions-from-resolved-file, --disable-package-repository-cache, --package-cache-path DIR Swift package resolution, matching the xcodebuild options of the same meaning

Build products

Product Location
.app and intermediates ~/DerivedData/<Name>-<hash>/ (change with --derivedDataDir)
.ipa <project dir>/build/<App>.ipa for Release, <App>-<Config>.ipa for other configurations

Common recipes

Goal Command
Install a Debug build on the iPhone kxbuild build .\MyApp.xcodeproj --install
Release .ipa for the App Store kxbuild build .\MyApp.xcodeproj -c Release --export app-store
Sign with a Distribution certificate chosen on the command line kxbuild build .\MyApp.xcodeproj -c Release -D CODE_SIGN_IDENTITY="Apple Distribution"
Set version and build number for one build kxbuild build .\MyApp.xcodeproj -D MARKETING_VERSION=1.2.0 -D CURRENT_PROJECT_VERSION=45
Check that it compiles, without signing kxbuild build .\MyApp.xcodeproj -D CODE_SIGNING_ALLOWED=NO
Simulator SDK compile check kxbuild build .\MyApp.xcodeproj --sdk iphonesimulator -D CODE_SIGNING_ALLOWED=NO
Build one library target only kxbuild build .\MyApp.xcodeproj -t MyKit --ignoreDependence
Reset Swift package caches kxbuild project resolve .\MyApp.xcworkspace --force
List schemes, targets and bundle IDs kxbuild project info .\MyApp.xcodeproj

kxbuild run options

kxbuild run takes the same build options as kxbuild build (-s, -c, -D, --clean, -j, --explain, --no-cache and the Swift package options), plus:

Option Description
--udid UDID, --connection-type USB|Network The device to run on and how to reach it. Defaults to the first connected device, over USB when both work
--no-build / --no-install Installs and launches the last build / launches the app already on the device
--kill-existing, --args "…", --launch-timeout D Ends a running instance first, passes launch arguments, sets how long to wait for the app to start (default 60s)
--wait-logs D, --log-file FILE Collects the app's logs (os_log, Logger, NSLog) for this long after the launch, optionally into a JSON-lines file
--screenshot FILE, --view-hierarchy FILE Saves a PNG screenshot and the view hierarchy as JSON after the launch

kxbuild test options

kxbuild test runs on a connected device with iOS 17 or later and takes the same build options as kxbuild build, plus --udid and --connection-type as above and:

Option Description
--test-plan NAME / --test-target NAME Uses this test plan of the scheme / runs these test targets instead of the scheme's test action
--only-testing T[/C[/m]], --skip-testing T[/C[/m]] Runs only / skips these tests, repeatable, like xcodebuild
--build-only / --xctestrun FILE Builds and writes the .xctestrun without running it / runs an .xctestrun without building

🔁 Scripts and CI

All commands exit with 0 on success and non-zero on failure. A typical CI command for a release .ipa:

kxbuild build MyApp.xcworkspace -s MyApp -c Release --export app-store --clean --derivedDataDir ./out --skip-package-updates --ipa ./out/MyApp.ipa --json

With --json, every line on stdout is one JSON event (log, progress, diagnostic, and a final result):

{"type":"progress","phase":"CompileSwiftSources","current":12,"total":42,"target":"MyApp"}
{"type":"result","command":"build","schemaVersion":1,"data":{"success":true,"duration":"1m12s","output":"…","products":["…"],"ipa":["out/MyApp.ipa"],"schemaVersion":1}}

Leave --json off when troubleshooting, because error details appear only in the normal output. Set KXBUILD_NO_UPDATE_CHECK to turn off update prompts in CI.

🔧 xcodebuild Compatibility

The bin folder of the install directory contains xcodebuild, xcrun and codesign, named the same as on macOS. When React Native, Expo, Flutter or Cordova scripts — or your own scripts — call them, they run kxbuild's versions, so they work unchanged. On macOS the system's own commands stay first on PATH, so use kxbuild build there.

xcodebuild -workspace ios/MyApp.xcworkspace -scheme MyApp -configuration Debug -sdk iphoneos
xcodebuild -list -json
xcodebuild -showBuildSettings -project MyApp.xcodeproj
xcrun --sdk iphoneos --show-sdk-path
Supported
Actions build (default), clean, install, installhdrs, installapi, installsrc, archive (minimal, unsigned .xcarchive), build-for-testing, test, test-without-building (tests run on a connected iOS 17+ device)
Selection -project, -workspace, -scheme, -target, -alltargets, -configuration, -sdk, -arch, -toolchain, -destination
Settings -xcconfig PATH, KEY=VALUE
Output -derivedDataPath, -archivePath, -clonedSourcePackagesDirPath, -resolvePackageDependencies
Queries -list, -showBuildSettings, -showsdks, -showdestinations, -version, with -json
Control -jobs, -quiet, -verbose, -hideShellScriptEnvironment

-exportArchive signs the archive for the method in ExportOptions.plist (app-store-connect, release-testing, enterprise, debugging, or the older names) with the certificate and profile in keychain, and writes the .ipa to -exportPath.

Not supported: analyze, docbuild, -create-xcframework, localization import/export and platform downloads. Other xcodebuild options are accepted and ignored. Exit codes follow xcodebuild: 64 usage error, 65 build failure or unsupported action, 66 input file not found. You can also get the App Store .ipa in one step with kxbuild build -c Release --export app-store.

xcrun finds and runs SDK and toolchain tools (--show-sdk-path, --show-sdk-version, -f TOOL, xcrun clang …). codesign signs and verifies with the same options, output and exit codes as on macOS.

🔏 Signing

You need a .p12 certificate (with its private key) and a .mobileprovision profile from your Apple Developer account: Apple Development + a development profile containing your iPhone's UDID for testing, Apple Distribution + an App Store profile for release.

Put them in a keychain folder. The one in the project root applies to that project; the one under KXBUILD_HOME is shared by all projects. Both are merged, and on macOS the system keychain is used too.

keychain/
├─ development.p12
├─ distribution.p12
├─ MyApp_Dev.mobileprovision
├─ MyApp_AppStore.mobileprovision
└─ password.properties

password.properties has one file=password line per certificate (file name exactly as on disk, no quotes):

development.p12=123456
distribution.p12=123456

As in Xcode, the project's signing settings decide which certificate and profile are used: CODE_SIGN_IDENTITY, DEVELOPMENT_TEAM, and either automatic matching by bundle ID and team or PROVISIONING_PROFILE_SPECIFIER. Override them for one build with -D. Without a certificate the project still builds, but the product is unsigned and won't install on an iPhone.

📱 Installing on a Device

kxbuild installs kxdevice alongside it for talking to iPhones over USB.

kxdevice doctor                   # check and repair device support (usbmuxd)
kxdevice device list              # first column is the UDID
kxbuild build .\MyApp.xcodeproj --install
kxdevice install .\build\MyApp.ipa
OS kxdevice doctor
Windows Starts the Apple Mobile Device Service (one admin approval); if it is missing, install and open Apple Devices from the Microsoft Store first
WSL Uses the Windows-side service through a relay. Plug the iPhone into Windows; don't pass it through with usbipd
Linux Installs and starts usbmuxd and its udev rules (needs sudo)
macOS Nothing to install

With several devices connected, --install uses the first one; pass --udid to kxdevice to choose.

🔍 Troubleshooting

kxbuild: command not found after installing

Open a new terminal so the updated PATH takes effect. If it still fails, check that the bin folder of the install directory is on PATH.

The build can't find headers or modules from Pods

You built the .xcodeproj. Run pod install, then build the generated .xcworkspace.

Debug build fails to link with undefined symbol: …vpfi

A known issue in the open-source Swift compiler when compiling file by file. Set KXBUILD_SWIFT_WHOLE_MODULE=all (or pass -D KXBUILD_SWIFT_WHOLE_MODULE=all for one build) to build every Swift target as a whole module.

No signing certificate matching '…' found

The keychain folder has no certificate of the type or team the project asks for. Add the matching .p12, or use -D CODE_SIGN_IDENTITY=… -D DEVELOPMENT_TEAM=….

Something else fails

Run kxbuild doctor -v (with the project path, if it's project-specific). It fixes most environment problems; its output is the most useful thing to include in a bug report.

🗂️ Sample Apps and Templates

These sample apps build and run on iPhone with kxbuild from Windows, Linux or macOS. The templates behind kxbuild project create live in their own repository, open to suggestions:

Repository What's inside
SwiftUI Gallery 15 SwiftUI demos: controls, lists, animation, gestures, Swift Charts, MapKit, SwiftData
UIKit Gallery (Objective-C) 14 UIKit demos in Objective-C, every view built in code
Flutter Gallery Material and Cupertino widgets plus four complete sample apps
React Native Gallery 16 demos of React Native's built-in components and APIs
Expo Gallery 22 Expo SDK modules: camera, sensors, location, SQLite and more
Godot Gallery 10 Godot 4 demos exported to iOS
Unity Gallery 10 Unity 6 demos exported to iOS
KXBuild App Templates Project and target templates for kxbuild project create and add-target

📣 Feedback

🐛 Found a problem or have a suggestion? Open an Issue
Please include the output of kxbuild version and kxbuild doctor -v, plus the full log of the failing command.
⭐ Find it useful? Star this repo, or Watch it to hear about new releases.

Popular repositories Loading

  1. kxbuild kxbuild Public

    Command-line iOS build system for Windows, Linux and macOS. Drop-in xcodebuild alternative with xcrun and codesign: builds .xcodeproj, .xcworkspace and Swift packages unchanged, signs with your .p1…

    11

  2. flutter-gallery flutter-gallery Public

    Flutter Gallery updated for Flutter 3.47: Material and Cupertino widget catalog with the Reply, Shrine, Rally and Crane sample apps. Build and run it on iPhone from Windows, Linux or macOS with KXB…

    Dart

  3. react-native-gallery react-native-gallery Public

    React Native Gallery: 16 interactive demos of React Native core components and APIs in TypeScript (FlatList, Animated, PanResponder, Modal, TextInput, Share, Linking…). Build and run on iPhone from…

    TypeScript

  4. expo-gallery expo-gallery Public

    Expo Gallery: 22 Expo SDK 58 module demos with Expo Router (expo-camera, expo-image, expo-sqlite, sensors, location, haptics, SF Symbols, Liquid Glass…). Build and run on iPhone from Windows, Linux…

    TypeScript

  5. godot-gallery godot-gallery Public

    Godot Gallery: 10 Godot 4 mobile demos in GDScript (UI controls, tweens, particles, 2D and 3D physics, 2D lights, shaders, PBR materials, touch and sensors, audio synth). Export to iOS and build on…

    GDScript

  6. unity-gallery unity-gallery Public

    Unity Gallery: 10 Unity 6 mobile demos in C# (uGUI, 3D and 2D physics, particle systems, PBR materials, procedural mesh, touch and sensors, audio synth). Export to iOS and build on Windows, Linux o…

    C#