Tips & Tricks

Run Configurations vs Schemes

The way AppCode deals with running and debugging an application is slightly different from how Xcode does it, and from time to time we get questions on the whole run/debug configurations concept and various aspects of the behaviour. We decided to dot the i’s on this matter with this post.

What are run configurations?

You all work with Xcode schemes, and you know that a scheme defines a collection of targets to build, a configuration to use when building, and a collection of tests to execute.
Run configurations in AppCode are based on Xcode schemes and are kept synced with Xcode schemes.

So when you open your project in AppCode for the first time, as long as you had schemes in Xcode, AppCode will fetch them and you’ll have run configurations you can already use without need for further modification.
You can also create some new run configurations in AppCode and give them distinctive names.

How to create a run configuration in AppCode?

This one’s easy – you open Run | Edit Configurations from the main menu, and see a dialog where you already have some run configurations; to create a new one click the plus icon and choose the kind of configuration: application or test.

Say, we’ve created an Application run configuration, now we need to adjust the settings taken from the default one.

Note: The defaults are like templates, they are only applied when you create a run configuration, they do not affect in any way your existing configurations. You can modify the default configurations settings in the same Run/Debug Configurations dialog: they are stored under Defaults in the tree to the right in the dialog.

So what are the options you can specify in an Application run configuration?

  1. Name, naturally.
  2. Choose a target, if you have several targets in your Xcode project.
  3. Configuration – corresponds to Build Configuration setting in Xcode.
  4. Executable, Program arguments (arguments passed on launch), Environment variables – same as in Xcode.
  5. “Make application active after launch” option means that once the application is launched the focus will be switched to it, while AppCode will go to background.

Most of the options aren’t new, right?
Note, that run configurations that you create in AppCode are not transferred to Xcode on the fly – you need to restart Xcode if you want it to fetch run configurations created in AppCode.

How to run a configuration in AppCode?

There are several ways you can launch a run configuration in AppCode:

  • Choose a run configuration and destination (an iOS device or a simulator) in the Navigation bar and click Run icon.
  • Hit Ctrl+R to launch the configuration that is selected in the Navigation bar.
  • Hit Ctrl+Alt+R to invoke a popup with the list of configurations and choose the one you want to launch. In this popup you can use speed search, i.e. if you have a long list of configurations you can just start typing the name of the needed one, and the list will be filtered to the matching configurations. If you want to view the settings or edit a configuration you see in the popup, select it and hit F4. To open the Run/Debug Configurations dialog from the popup, hit 0.

The shortcuts for debug are similar – Ctrl+D to start debug session with currently selected run configuration, Ctrl+Alt+D to invoke popup and choose configuration to debug. Also you can switch between run and debug mode in the popup by holding Shift.

How to change target destination?

You can change the target destination from the Simulator to device and back from the Navigation bar or from the Run popup menu.

Why are there two different actions: run and debug?

In AppCode unlike Xcode run and debug are two different actions. The reason is simple – sometimes you might just want to run your application and see what it will look like for your end users. In this case you don’t need to stop at breakpoints, and you can use run instead of debug.

Hint: You can run several configurations simultaneously, but not on the same device, nor simulator. Why would you need that? For instance you might want to quickly run a test without stopping an application that is already running. Or, you may have a complicated multi-process application.

Stay tuned for further posts in which we’ll cover AppCode test runner and debugger.

The AppCode Team