UserGuide

iOS Simulator

From Xojo Documentation

Xojo runs your iOS apps in the iOS Simulator for testing and debugging. The iOS Simulator is part of the Xcode download, so you'll need to make sure it is installed before trying to run your Xojo iOS projects.

Refer to the UserGuide:Xcode Setup topic for information on how to install Xcode.

Running Your App

Eddie's Electronics Running in iOS Simulator
iOS Simulator Device Property

To run your iOS app in the iOS Simulator, click the Run button on the Xojo toolbar. Your project is compiled and the app starts the iOS Simulator for the device specified in the Simulator Device property for the iOS Build Setting. Change this to the type of device you want to use for testing.

When you run the app in the Simulator, you can use the Xojo debugger where you can set breakpoints to stop at the line of code, and then step through the code and look at variable values.

Running in the Simulator is fast and convenient, but you should also always test your apps on actual devices as the Simulator does not work exactly like a device. Some differences when running in the Simulator include:

  • Apps built for the Simulator use the 32-bit x86 compiler, not the 64-bit ARM compiler. This can result in different app behavior.
  • Not all device features are available in the Simulator.
  • Keyboard may work differently in the Simulator.

You may have noticed that the iOS entry in Build Settings has a build step called "Sign". This build step is used to code-sign your iOS app when you build it for deployment. You cannot change its properties and you should not remove it.

Tips

When you use Copy File Steps to copy files to your iOS app on the Simulator, the files are copied to special locations on the Mac itself. These files are not removed between runs of your app.

For complete information about the iOS Simulator, refer to the official Apple iOS Simulator User Guide. The tips below are from the section Interacting with the iOS Simulator:

Gesture Description
Two Finger Drag
  1. Place the pointer where you want the two-finger drag to occur.
  2. Hold down the Option key.
  3. Move the circles that represent finger touches to the start position.
  4. Move the center of the pinch target by holding down the Shift key, moving the circles to the desired center position, and releasing the Shift key.
  5. Hold down the Shift key and the mouse button, move the circles in the direction you want to drag, and release both the Shift key and the mouse button.
Pinch
  1. Place the pointer where you want the pinch to occur.
  2. Hold down the Option key.
  3. Move the circles that represent finger touches to the start position.
  4. Move the center of the pinch target by holding down the Shift key, moving the circles to the desired center position, and releasing the Shift key.
  5. Hold down the mouse button, move the circles in and out to the end position, and release the Option key.
Rotate
  1. Place the pointer where you want the rotation to occur.
  2. Hold down the Option key.
  3. Move the circles that represent finger touches to the start position.
  4. Move the center of the pinch target by holding down the Shift key, moving the circles to the desired center position, and releasing the Shift key.
  5. Hold down the mouse button, rotate the circles to the end position, and release the Option key.

Removing Unused Devices from the iOS Simulator

You may find that the list of iOS devices and iOS versions for the iOS Simulator contains many more information than you need. For example you may not really need to have iPhone 5, 5s and SE listed in the iOS Simulator.

To remove older devices that you no longer need from the iOS Simulator, you’ll need to go to Xcode and open the "Devices and Simulators" window (in the Window menu). Select the "Simulators" tab to see all the iOS Simulator devices that are installed. If you have multiple iOS versions installed then you'll see devices listed more than once since each device is listed for each version of iOS. For example you may see iPhone 6s listed for both iOS 11.0 and iOS 10.3.1.

To remove a device, such as iPhone 5 running iOS 10.3.1, select it from the list, right-click on it and from the menu select "Delete". Choose "Delete" again from the "Are you sure?" prompt. The device will no longer appear in this list and the next time you open Xojo the device will no longer appear in the iOS Build Settings Simulator Device pop-up menu.

This Terminal command can also removed all unavailable devices that are left over from older versions of Xcode:

xcrun simctl delete unavailable

Troubleshooting

  • If your app launches in the Simulator but has a blank screen, be sure to verify that all your image paths are correct.
  • If your app is immediately crashing on launch, add the iOSApplication.UnhandledException event and put code there (or a Break command) to see if that provides additional information.

iOS System Logs

If you app crashes while running in the iOS Simulator, you can view the system logs for the crash by selecing Debug ↠ Open System Log from the menu. You can also open the Console app to look at the All Messages view, which will also have additional information, including a link to the crash log itself. If you find a crash, please create a Feedback case and attach the crash log.