Develop iOS apps with CocoaPods on Windows

Keep your Podfile as it is. Run pod install on Windows and build the generated workspace.

On Windows, iOS projects that use CocoaPods keep managing dependencies with pod, and you build, install and debug on your iPhone, all on Windows. CocoaPods is installed along with KXBuild, so pod runs in any terminal. Your Podfile and project need no changes, whether the project is Swift or Objective-C.

Steps

Run doctor

Doctor checks CocoaPods and installs it if it's missing.

Use either of these

VS Code extension
In the title bar of the KXBuild view, open the ··· menu and run Doctor (fix environment).
Command line

> kxbuild doctor

When it finishes, open a new terminal. If this prints a version number, you're ready.

> pod --version

Create a project

For a new project, use the template that comes with a Podfile. It runs pod install after creating the project, so you can skip to step 4.

Use either of these

VS Code extension
Run KXBuild: New Project from the Command Palette and pick the "iOS App (Swift, CocoaPods)" template.
Command line

> kxbuild project create -t app_swift_cocoapods -n MyApp -o D:\projects

If an existing project has no Podfile yet, create one in the folder containing the .xcodeproj. If it already has one, go to the next step.

> pod init

Add dependencies

List the libraries each target needs in the Podfile. The version syntax is in the appendix at the end of this page.

platform :ios, '15.0'
use_frameworks!

target 'MyApp' do
  pod 'Alamofire', '~> 5.9'
  pod 'SDWebImage'
end

Then install from the folder containing the Podfile. This downloads the dependencies and creates the Pods folder, Podfile.lock and MyApp.xcworkspace.

> pod install

From now on, build and debug the .xcworkspace. The .xcodeproj can't find the libraries in Pods. Run pod install again every time you change the Podfile. Commit Podfile.lock to version control so everyone on the team installs the same versions.

Write code

In VS Code, open the folder containing the Podfile with File > Open Folder…, and set the startup project to the .xcworkspace in the KXBuild view. Your source files get completion, go to definition and error checking, and libraries in Pods get completion and go to definition after the first build. If completion misbehaves, see Code completion and indexing.

Debug

Connect your iPhone over USB, select it in the KXBuild view and press F5. KXBuild builds, installs and stops at your breakpoints. You can set breakpoints in your own code and in any Pods library that ships its source.

Release

Build with the Release configuration to get build\MyApp.ipa in the project folder. To upload it to App Store Connect, see Release and App Store submission.

Use either of these

VS Code extension
Switch the configuration to Release in the Build configuration node of the KXBuild view, then run KXBuild: Build from the Command Palette.
Command line
Build the workspace that pod install created.

> kxbuild build .\MyApp.xcworkspace -c Release

Update dependencies

pod install only installs the versions recorded in Podfile.lock and never upgrades libraries you already have. To upgrade, first see which libraries have newer versions, then update all of them or just the ones you name.

> pod outdated

> pod update Alamofire

pod update without a library name upgrades every library within the ranges your Podfile allows. If a version that was just released can't be found, add --repo-update to refresh the local spec index first.

Troubleshooting

Problem	Fix
The build can't find headers or modules from Pods	You're building the .xcodeproj. Build the .xcworkspace instead. If you just changed the Podfile, run pod install first
The sandbox is not in sync with the Podfile.lock	Podfile.lock changed when you pulled. Run pod install
Dependencies are in a bad state and you want to start over	Delete the Pods folder and run pod install again. If that doesn't help, clear the cache with pod cache clean --all
The pod command isn't found	Run doctor, then open a new terminal

Appendix: pod commands and version syntax

Command	What it does
pod init	Creates a Podfile for the project in the current folder
pod install	Installs dependencies from the Podfile and Podfile.lock and creates the .xcworkspace
pod update [name]	Upgrades all libraries or the named one, and updates Podfile.lock
pod outdated	Lists libraries that have newer versions
pod repo update	Refreshes the local spec index
pod search keyword	Searches for available libraries
pod cache clean --all	Clears the download cache
pod deintegrate	Removes CocoaPods from the project

Podfile entry	Meaning
pod 'Alamofire'	Latest version
pod 'Alamofire', '5.9.1'	Exactly this version
pod 'Alamofire', '~> 5.9'	5.9 or later, below 6.0
pod 'Alamofire', '>= 5.0'	5.0 or later
pod 'MyKit', :path => '../MyKit'	A library in a local folder
pod 'MyKit', :git => 'https://…/MyKit.git', :tag => '1.0.0'	A specific version from a Git repository

Next steps

Objective-C

Open your existing Xcode project and build. No changes needed.

Swift

Open an Xcode project and build, with SPM dependencies resolved automatically. Pure Swift packages can be converted to an app to produce an .ipa.

Don't see your framework?

kxbuild is a general-purpose build toolchain, so if your framework produces an Xcode project, KXBuild can build it. The list above covers common cases only. Tell us about your setup.

admin@kxbuild.net All stacks