Build and configure
Debug versus Release, choosing a scheme, target and configuration, overriding build settings, where build products go, when you get an .ipa and when Swift package dependencies resolve.
Build in VS Code and kxbuild build on the command line do the same thing. They compile, link, sign and package using the project's schemes, configurations and build settings. The default is Debug. A Release build of an iOS app writes an upload-ready package to build\<App>.ipa in the project folder. For every option, see the kxbuild command reference.
> kxbuild build .\MyApp.xcodeproj -s MyApp -c ReleaseSchemes, targets and configurations
You can build a .xcodeproj, a .xcworkspace or a folder with a Package.swift. Without a scheme or target, KXBuild builds the default scheme. The configuration defaults to the scheme's Run configuration, or Debug if there isn't one. To list a project's schemes, targets and bundle IDs, run kxbuild project info.
| Option | VS Code | Command line |
|---|---|---|
| Project | The startup project in the KXBuild view | First argument |
| Scheme / target | The startup project's default scheme. With several targets you're asked to pick one. Build on a target node builds just that target. | -s NAME / -t NAME. Add --ignoreDependence to skip dependencies. |
| Configuration | The Build configuration node in the KXBuild view or KXBuild: Select Build Configuration | -c Debug|Release or a custom configuration name |
| SDK / architecture | Always iphoneos · arm64 | --sdk, --arch |
Debug and Release
| Debug | Release | |
|---|---|---|
| Use for | Breakpoint debugging on a device | TestFlight, the App Store or Ad Hoc distribution |
| Optimization | Off, so breakpoints land where you expect | On, so breakpoints can jump around |
| Certificate | Usually Apple Development | Apple Distribution for App Store submission |
| .ipa | Not by default. Add --ipa PATH to get one. | Written to build\<App>.ipa for iOS apps by default. --no-ipa turns it off. |
Override build settings for one build
-D KEY=VALUE overrides any build setting for one build. You can repeat it, and it takes the same precedence as KEY=VALUE in xcodebuild. --xcconfig FILE applies a whole file at once.
> kxbuild build .\MyApp.xcodeproj -c Release -D CODE_SIGN_IDENTITY="Apple Distribution" -D DEVELOPMENT_TEAM=ABCDE12345> kxbuild build .\MyApp.xcodeproj -D MARKETING_VERSION=1.2.0 -D CURRENT_PROJECT_VERSION=45For permanent changes, edit the project file itself in the Project Settings Editor.
Build products
| Product | Location | Notes |
|---|---|---|
| .app and intermediates | ~\DerivedData\<ProjectName>-<hash>\ | --derivedDataDir DIR changes the root. --clean empties it before building. |
| .ipa | <project folder>\build\<App>.ipa | Written by default for iOS apps. Configurations other than Release are named <App>-<Config>.ipa. -o, --ipa PATH sets the path, and --no-ipa turns it off. |
| <App>.AppStoreInfo.plist | Next to the .ipa | The upload descriptor for the -assetDescription option of command-line Transporter |
In WSL, keep the project on the Linux side. Under /mnt/c, builds are an order of magnitude slower.
Simulator SDK
Use --sdk iphonesimulator to check that your code compiles for the simulator. Simulator builds are usually unsigned.
> kxbuild build .\MyApp.xcodeproj --sdk iphonesimulator -D CODE_SIGNING_ALLOWED=NOSwift package dependencies
If the project uses Swift packages, they're resolved automatically before the build. To force a fresh resolve, like Xcode's Reset Package Caches, run
> kxbuild resolve .\MyApp.xcworkspace --forceIn CI, add --only-use-versions-from-resolved-file to stick strictly to Package.resolved, and --skip-package-updates to avoid contacting remote repositories. Both build and resolve accept them.
Metal shaders
If the project contains .metal files, install Apple's Metal Developer Tools for Windows first. The download requires signing in with an Apple Account, so doctor can't install it for you. Download it once yourself. Open the Apple downloads page, sign in, download the latest Metal Developer Tools for Windows in the list and install it with the default options. See Metal developer tools for what's included. Then just build. KXBuild finds the tools on its own, with no PATH changes needed. Linux has no Metal compiler, so build these projects on Windows.
Install on your iPhone after building
> kxbuild build .\MyApp.xcodeproj --installAfter a successful build, this installs the signed app on the connected iPhone. With several connected, it uses the first one. In VS Code the equivalent is Build & Run, which also attaches the debugger. See Run and debug.
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 |
| Debug .ipa at a path of your choice, to send to testers | kxbuild build .\MyApp.xcodeproj --ipa D:\out\MyApp-dev.ipa |
| Build only one library target | kxbuild build .\MyApp.xcodeproj -t MyKit --ignoreDependence |
| Check that it compiles, without signing | kxbuild build .\MyApp.xcodeproj -D CODE_SIGNING_ALLOWED=NO |
For scripts and CI, see the kxbuild command reference.
Next steps
Release and App Store submission
Build Release with a Distribution certificate to get an .ipa, upload it to App Store Connect with Transporter or Appuploader, then go through TestFlight and App Review. Ad Hoc and enterprise distribution work the same way.
Troubleshooting
Run kxbuild doctor first. Then look up your error message by category: install, project, signing, device, release or extension. Also covers where to find the logs.