Modaal builds and runs your iOS app with Apple’s Xcode. This guide takes you from zero to a working setup — install Xcode, download the iOS simulators, and let Modaal confirm everything’s ready.
Xcode is Apple’s development environment for building and running iOS apps. Modaal drives it for you behind the scenes — you never have to write Swift in Xcode or wire up a project there. You just need it installed, opened once, and with the iOS simulators downloaded. Modaal does the rest.
Everything is driven from one place inside Modaal. Click your profile avatar in the top-right corner to open the User Menu, then choose Set up Xcode.
User Menu → Set up Xcode. The colored dot shows your current status — green when Xcode is ready, orange when it still needs attention.
Keep this panel open while you work through the steps below. After each step you’ll come back to it and press Check / Re-check to let Modaal re-detect your setup.
Step 2 — Open Xcode once and download the simulators
This is the step that trips most people up. Installing Xcode is not enough — you have to launch it once so it can finish its own setup and download the iOS simulators. Until you do, Modaal shows Attention needed:
“Attention needed” — Xcode is installed (note the path and version), but Runtimes show “None” and there are no iOS Simulators yet.
1
Launch Xcode and accept the license
Open Xcode from your Applications folder. The first time it runs, it asks you to agree to the Xcode and Apple SDKs Agreement. Read it, then click Agree (you’ll be asked for your Mac password).
First launch asks you to accept the license agreement.
2
Choose the iOS platform and download it
Xcode then offers to install platform components. Make sure iOS is checked and click Download & Install. You can leave watchOS, tvOS, and visionOS unchecked — Modaal only needs iOS to build and run iPhone apps.
Tick iOS, then Download & Install. iOS is the only platform Modaal needs.
If Xcode doesn’t show this screen on launch, you can trigger it any time from Xcode → Settings… → Components, then download an iOS simulator runtime.
3
Wait for the simulator runtime to download
The iOS simulator runtime is several gigabytes and downloads in the background. You can watch progress in Xcode’s Downloads window.
The iOS simulator runtime downloading. Let it finish completely.
4
Confirm it finished
When the download completes, the runtime shows a checkmark and Xcode opens its welcome window. Xcode is now fully set up.
Download complete — the iOS simulator runtime is installed.
You can quit Xcode now — Modaal launches it on its own when it needs to build.
Go back to Modaal’s Set up Xcode panel and click Re-check. Modaal probes your installation and, when everything’s in place, switches to Installed (green) and lists the iOS simulators it found.
“Installed” — Xcode is set up with iOS simulators. You're ready to build and run.
That’s it — you can now ask Modaal to build and run your app, and it’ll launch it on the iOS simulator for you.
You can also re-validate from the User Menu via Run system check, which re-checks Xcode along with Modaal’s other prerequisites.
If you keep several Xcode versions (for example a stable release and a beta), Modaal lists each one and marks which is active — the one macOS will use for builds. To switch, click Set as active on the version you want.
With multiple Xcodes installed, click “Set as active” on the one you want Modaal to build with.
macOS asks for your administrator password to make the switch (it runs Apple’s xcode-select under the hood). If the button ever fails, the panel shows the exact command you can run yourself in Terminal:
Modaal still says “Attention needed” after installing Xcode
You almost certainly skipped Step 2. Installing Xcode is not enough — open it once, accept the license, and download an iOS simulator runtime from Xcode → Settings… → Components. Then click Re-check in Modaal.
“Runtimes: None” / no iOS Simulators listed
The simulator runtime hasn’t been downloaded. In Xcode, go to Settings… → Components, download an iOS runtime, wait for it to finish, then Re-check in Modaal.
The build succeeded but no simulator window appeared
On recent Xcode versions the simulator viewer can’t launch when Xcode is installed on an external or ownership-disabled volume. Move Xcode to your internal /Applications folder, or re-enable ownership on the volume with sudo diskutil enableOwnership <volume>. The build itself still ran — this only affects showing the window.
“Set as active” keeps failing
Make sure you entered the correct administrator password. As a fallback, copy the sudo xcode-select -s … command the panel shows and run it directly in Terminal.
I'm running low on disk space
Xcode plus simulators can easily use 30–50 GB. Remove old simulator runtimes you don’t need from Xcode → Settings… → Components, and check → System Settings → General → Storage for other large items.
Still stuck? Join our community on Discord — we’re happy to help you get set up.
.svg?fit=max&auto=format&n=rBROILWhBGfA_4EY&q=85&s=0185f3e9df88428c430b0b130b94d569)
