Debugging Programs Remotely
With remote graphical debugging in Xcode, you can debug a program running on another computer as you would any local executable, without resorting to the command line. Use remote debugging when you cannot easily debug your program on the computer that it is running on. For example, you may be trying to debug a full-screen application, such as a game, or a problem with event handling in your application’s GUI. Interacting with the debugger on the same computer interferes with the execution of the program you are trying to debug. In these cases, you have to debug the program remotely.
This chapter introduces remote debugging in Xcode and walks you through enabling remote debugging in Xcode. To set up your project for remote debugging, you must perform the steps described in the following sections:
Configuring Remote Log-in describes how to configure your local computer and the remote host to allow remote login using SSH public key authentication.
Creating a Shared Build Location describes how to set up a shared build directory that both computers can access via the same path.
Configuring an Executable for Remote Debugging describes how to configure the executable of the program you wish to debug for remote debugging in Xcode.
Configuring Remote Log-in
Remote debugging in Xcode relies on SSH public key authentication to create a secure connection with the remote computer. To facilitate authentication, Xcode integrates with
ssh-agent. This lets you use encrypted private keys for added security without having to reenter your passphrase each time Xcode establishes a connection to the remote host. If you already use a third-party utility to set up the environment variables used by
ssh-agent, Xcode attempts to use those settings. Otherwise, Xcode uses its own agent for authentication.
Before starting a remote debugging session, you need to be able to log in to the remote computer. To do this, you must:
Turn on remote login on the computer that will host the program being debugged.
In System Preferences, choose Sharing, Remote Login.
Ensure that you can connect to the remote host using SSH public key authentication.
If you are unsure whether you are using SSH public key authentication, you can test this by logging in to the remote computer with
If you are prompted for the user’s password, you are not using public key authentication.
If you are prompted for a passphrase—or for nothing at all—you are already using public key authentication.
If you are not set up to log in to the remote host using SSH public key authentication, you need to create a public/private key pair, and configure the local and host computers to use it. You can do so with the following steps:
Generate a public and private key pair using
On the command line, type the following line:
ssh-keygen -t dsa
You should see output similar to the following:
Generating public/private dsa key pair.
Enter file in which to save the key (/Users/admin/.ssh/id_dsa):
/Users/admin/.ssh/id_dsa already exists.
Overwrite (y/n)? y
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /Users/admin/.ssh/id_dsa.
Your public key has been saved in /Users/admin/.ssh/id_dsa.pub.
The key fingerprint is:
Copy the public key to the
authorized_keysfile on the remote computer.
This file is usually stored at
~/.ssh/authorized_keys. If the
authorized_keysfile already exists on the remote computer, be careful not to overwrite the file. You can add the public key, which is stored in the file you specified to
id_dsa.pubby default), by entering the following on the command line:
cat id_dsa.pub >> ~/.ssh/authorized_keys
Make sure that the
authorized_keysfile is not readable by anybody else.
Change the permissions on the file by entering the following on the command line:
chmod go-rwx ~/.ssh/authorized_keys
Test the connection by logging in to the remote computer using
From the command-line, type
ssh <username>@<hostname>. Ensure that you are not asked for the user’s password. If you did not leave it empty in step 1, you should be prompted for your passphrase, as in the following example:
Enter passphrase for key '/Users/admin/.ssh/id_dsa':
If you are debugging a GUI application, you must be logged in to the remote computer as the same user that you connect to using
ssh. This user must have permission to read the build products.
Creating a Shared Build Location
For remote debugging to work, both computers—both the local computer running Xcode and the remote host running the program you are debugging—must have access to your project’s build products and intermediate files. You can do this in either of two ways:
Create a single shared location. This is easiest with a network home directory, although you can use any shared folder that both computers can access. In Xcode, set the build products and intermediates location to this shared folder. If necessary, create symbolic links to the build folder on the remote host so the path to the build products is the same on both computers. For details on how to set the location of the build folder in your Xcode project, see Build Locations.
Copy the files to the remote host. Alternatively, you can copy the build products and intermediate files over to the remote host after each build, although this is considerably less convenient. These files must be located at the same path on the remote computer.
Configuring an Executable for Remote Debugging
After you have configured both computers to allow for remote login and have set up a common build products location, the last step is configuring the executable you want to debug remotely. You may consider creating a separate custom executable environment for remote debugging. Using separate executable environments, you can specify different options for debugging remotely and debugging locally and easily switch between the two modes.
See Executable-Environment Debugging Information to learn how to configure an executable for remote debugging.
To start a remote debugging session, make sure the active executable is correctly set, then build and debug your product as normal. Before it launches the executable, Xcode displays an authentication dialog that asks you to type in your passphrase. After you have authenticated once, Xcode does not prompt you for your passphrase again until the next time you initiate a remote debugging session after restarting Xcode.
If you are experiencing problems debugging on the remote host, look in the console for error messages. To view the console, choose Run > Console.