Executable Environment Overview

The executable environment defines:

• What executable file is launched

• Command-line arguments to pass to the program upon launch

• Environment variables to set before launching the program

• Debugging options that tell Xcode which debugger to use and how to run the program under the debugger

Generally, you do not have to create executable environments; in most cases, Xcode does this for you. If you are creating a target that produces a product that can be run by itself—such as an application—Xcode automatically knows to use the application when you run the product.

However, if you have a product that can’t be run by itself—such as a plug-in for a third party application—you need to create your own executable environment. This custom executable environment specifies the program to launch when you run the product, such as the application that uses your plug-in.

Even if your target creates a product that can run on its own, you may also want to customize the executable environment associated with it, in order to pass arguments to the executable or test it with environment variables.

Executable environments defined for a project are placed in the Executables group in the Groups & Files list in the project window. Executable environments that you define are stored in your user file for the project—that is, in the .pbxuser file in the project package (see The Project Directory for details). As a result, each developer working on a project defines her or his own executable environments. When you run a product in Xcode, Xcode launches the program specified by the active executable, as described in the Setting the Active Executable.

Setting the Active Executable

The active executable is the executable environment that Xcode uses when you run a product. Xcode tries to keep the active target and the active executable in sync; if you set the active target to a target that builds an executable, Xcode makes that target’s executable the active executable. Otherwise, the active executable is unchanged. If you use a custom executable environment to test your product, you have to make sure that the active executable is correct for the target you want to run.

The active executable is indicated by the blue (selected) button in the detail view. To change the active executable, do either of the following:

• Choose the desired executable environment from the Set Active Executable submenu of the Project menu.

• Select Executables in the Groups & Files list and select the desired executable environment in the detail view.

Creating Custom Executable Environments

Many targets create a product that can be run by itself, such as an application or command-line tool. When you create such a target, Xcode adds an entry to the Executables group that points to the target’s product, and it knows to use that executable environment when you run the target.

Sometimes, though, you have a product that can’t run by itself: for example, a plug-in or a framework. Even if your product can run by itself, you may want to run the product under different conditions to test it. For example, you may want to test a command-line tool by passing it specific command-line arguments. Or you may have an application that performs differently depending on the value of an environment variable.

In these cases, you need to create a custom executable environment. You may have several executable environments for exercising the product of a single target. For example, you could have several applications that test different aspects of a framework. Or you could have several lists of command-line arguments and environment variables that test different aspects of a command-line tool.

You can also use custom executable environments to debug programs in Xcode, even if you do not have an Xcode project for the program. For example, you may have a program that you did not build in Xcode, or a program that was built by another person, to which you do not have the source. To run this program in the debugger, you simply create an empty project and add one or more custom executable environments that are configured to launch your program.

To create a custom executable environment, choose Project > New Custom Executable.

Xcode displays a dialog in which you can specify characteristics for your executable environment:

• Executable Name field. Enter the name used to identify the executable environment in Xcode.

• Executable Path field. Enter the path to the executable to launch, or click Choose and navigate to the executable file or application bundle.

• The Add To Project pop-up menu. Choose (among the currently opened projects) the project to which Xcode adds the custom executable.

When you click Finish, Xcode adds the new executable environment to the chosen project. You can change the program that Xcode launches when using this executable environment—along with other executable settings—in the Executable Info window, as described in Configuring Executable Environments.

Configuring Executable Environments

Executable environments give you control over how your product is run when you launch it from Xcode.

You configure executable environments using the Executable Info window. To open the Executable Info window:

1. Select the executable environment in the Groups & Files list or in the detail view.

2. Open the Executable Info window by choosing File > Get Info.

The following sections describe the settings you can configure in the Executable Info window.

• View and edit basic information about the executable environment, for example, you can view or edit the executable you are using or the working directory.

• Specify arguments to pass to the executable on launch, as well as any environment variables for Xcode to set before launching the executable.

• Specify which debugger to use when debugging the executable, as well as a number of other debugging options.

• Associate notes or other arbitrary text with the executable.

Executable-Environment General Settings

The General pane of the Executable Info window (Figure 10-1) lets you configure essential aspects of an executable environment.

These are the executable-environment aspects the General pane allows you to configure:

• Name field. The name of the executable environment.

• Path field. The path to the binary the executable environment runs.

• Path Type pop-up menu. Indicates whether path is an absolute path or a relative path (specifies the directory to which Path is relative).

• Suffix pop-up menu. Specifies whether to load normal, debugging, or profiling builds of the frameworks the product uses.

• Standard input/output pop-up menu. Specifies the device the product uses for standard input and output.

• Set the working directory to. Specifies the product’s working directory when running. See Build Locations for more information.

Executable-Environment Arguments

If your product takes command-line arguments, you can define those arguments in an executable environment. Xcode passes those arguments to the product’s binary when you run the product.

To test your product under different conditions, you can create multiple executable environments, each with different arguments. Changing your test environment becomes as simple as changing the active executable.

You specify arguments to pass to the binary, as well as environment variables that the executable environment sets before launching the binary, in the Arguments pane of the Executable Info window (Figure 10-2).

These are the executable-environment aspects the Arguments pane allows you to configure:

• “Arguments to be passed on launch” table. Defines command-line arguments. Individual arguments can be active or inactive, facilitating the testing of particular combinations of arguments. To reorder the arguments list, drag the argument line to its new location in the list.

• “Variables to be set in the environment” table. Defines environment variables for the running binary. Individual variables can be active or inactive. You can access the active variables during a run with getenv.

To learn more about the directories used in the build process, see Build Locations. For more information on these build settings, see Xcode Build System Guide.

Executable-Environment Debugging Information

Executable environments specify a set of debugging-specific items that specify which debugger to use, as well as how Xcode communicates with the debugger. (You debug a product when you start it with breakpoints activated.) You configure these items in the Debugging pane of the Executable Info window, shown in Figure 10-3.

These are the executable-environment aspects the Arguments pane allows you to configure:

• “When using” pop-up menu. Specifies the debugger to use when running with breakpoints.

• “Standard input/output” pop-up menu. Specifies the device the product uses for debug input and output.

• Debug executable remotely via SSH. Activates remote debugging using SSH. See Debugging Programs Remotely for more information.

  • Connect to: Specifies the host computer on which the binary runs.

• Start executable after starting debugger. Specifies whether the executable environment starts the binary immediately after loading it in the debugger. If so, Xcode loads the binary in the debugger but does not start it until you restart. This feature lets you perform debugging operations—such as setting breakpoints—before the binary runs. You may also use this option to attach to a running program.

• Wait for next launch/push notification. Specifies whether to attach to the binary when it launches. This is particularly useful when debugging push notifications. For more information, see Local and Remote Notification Programming Guide.

• Break on Debugger() and DebugStr(). Tells Xcode to set the USERBREAK environment variable, which suspends execution of the binary on calls to the Core Services framework debugging functions Debugger and DebugStr.

• Auto-attach debugger on crash. Tells Xcode to try to attach to the binary when it crashes.

• Additional directories to find source files in. Lists additional directories containing source files corresponding to the symbol information for the binary.

  If you have the source code to the application, you can make that source code available to the debugger so you can see the source for variables and set breakpoints. This operation makes your source code available to the debugger, but does not give you any of the source code navigation features of Xcode or make the source code available to you to set breakpoints before the debugging sessions starts. For this type of access, you can add the source code directly to your project, as described in Managing Files and Folders in a Project.