Components of an Xcode Project

A project contains and organizes everything you need to create one or more software products. Your Xcode project serves two important purposes; it:

1. Organizes build system inputs for building a product.

2. Maintains information on the items in your project and their relationships, to assist you in the development process.

To develop a product using Xcode, you must understand the key components of your project. Figure 2-1 shows a simplified representation of a project and its essential pieces.

The project’s contents include the following essential items; in the course of developing a product, you will work with each of these:

1. Files. Source files are the files used to build a product. These include source code files, resource files, image files and others.

   A project keeps all of the source files you use for a particular product or suite of related products. A project can also contain files that are not directly used by Xcode to build a product, but contain information that you use during the development process, such as notes, test plans, and more.

   In the course of developing a product you edit project files—using Xcode’s built-in editor or an external editor—to author source code for a product, and organize files into a target (described below) to define the build system inputs for creating the product.

   A project keeps a reference to each file you add to the project. A project can also contain folder references, if you want to manipulate a group of files as a whole; framework references to access the contents of a framework, or references to other projects. Files in a Project describes how Xcode stores these references and discusses the files in a project in more detail.

2. Targets. When it comes time to actually create, or build, a product, you use a target. A target defines a single product; it organizes the inputs into the build system—the source files and instructions for processing those source files—required to build that product. To create a finished product, build its target. Projects can contain one or more targets, each of which produces one product.

   Targets, and the products they create, may be related. If a target requires the output of another target in order to build, the first target is said to depend upon the second. Xcode lets you add target dependencies to express this relationship. Targets describes targets and the instructions they contain in more detail.

   For each target in your project, Xcode adds a product reference. This is a file reference to the output generated by the target, such as an application. You can use this product reference to refer to the products in your project the same way you use a file reference to refer to a file; however, the product reference does not actually refer to anything in the file system until you build the product.

3. Executables. After you’ve successfully built a product, you need to test it to make sure that it works. When it comes time to run or debug your product, you use an executable environment to tell Xcode how to do so. An executable environment tells Xcode

   1. What program to launch when you run or debug from within Xcode.

   2. How to launch the program. The executable environment lets you tell Xcode what command-line arguments to pass, environment variables to set, debugger to use, and so forth.

   If you are building a product that can be run on its own—an application, command-line tool, and so forth—Xcode automatically sets the default executable to the target’s product. However, if you have a product such as a plug-in or framework, you must create an executable environment to specify a program to run and test your product with.

   Even if your product generates an executable that can run on its own, you may want to customize the executable environment to specify command-line arguments for Xcode to pass to the program on launch, environment variables to set, and so forth. Executable Environments describes executable environments in Xcode in more detail, and explains how to modify executable settings.

   A project can contain any number of executables. There is not a one-to-one correspondence between targets and executables, although Xcode automatically creates an executable environment for each target that creates a product that can be run on its own. You can, however, define multiple executable environments to use to test the product of a single target under different circumstances.

In addition to these fundamental building blocks of the development process, your Xcode project also maintains a great deal of information about the items in your project and their current state. Figure 2-2 shows a representation of a project with this additional information.

Your Xcode project tracks:

• Organizational information that Xcode uses to help you do your work. For example, projects can contain groups to help you organize and find files, or bookmarks to your favorite locations. Xcode also maintains a symbolic index for your project; it uses this information to provide assistance such as code completion, project-wide symbol searching, and more. Groups and other features for organizing project contents are described in Organizing Xcode Projects; project-wide searches and other features for finding information in your project are described in Finding Information in a Project.

• Project-wide settings that affect the build process and other software-development operations for all targets and project items. For example, the project tracks the “active” target; this is the target that Xcode builds when you hit the Build button.

The settings that an Xcode project tracks include:

• Source control management system (SCM). Xcode supports the CVS, Perforce, and Subversion version control systems for managing changes to source code. Version Control describes how to choose a version control system and how to work with version control features in Xcode.

• Mac OS X SDK version. Using Xcode, you can develop software that can be deployed on versions of Mac OS X different from the one you are developing on. You can choose which version (or SDK) of Mac OS X headers and libraries to build with. Using Cross-Development in Xcode briefly describes how to choose a Mac OS X system version in Xcode. For detailed information, see SDK Compatibility Guide.

• Build styles. A build style lets you modify how a target is built. It contains build settings that let you override some of the information in a target, without creating a whole new target. In this way, you can rapidly try variations on a target without maintaining multiple copies. The project keeps track of the available build styles and their definitions. See Build Styles for more information on build styles in Xcode.

• Active target and build style. The active target is the target that gets built when you initiate a build in Xcode. The active build style is the build style that Xcode applies to the active target, and any targets it depends upon, when you build. See Setting the Active Target and Build Style for more information.

• Active executable. The active executable is the executable environment that specifies which program is launched, and how, when you run or debug from within Xcode.

Because active build style, choice of version control system, and SDK version are all attributes of the project, they must be the same for all targets in a project. For example, if you have a target that uses the Perforce source control system, you can’t have another target in the same project that uses the CVS system. You can, however, use cross-project references and dependencies to tie together targets in separate projects that use different version control systems.

A project can have multiple targets and multiple executables. However, there can only be one active target, one active build style, and one active executable. So, for example, if a project builds more than one application, only one executable—corresponding to one application—can be active and that’s the only executable you can debug in Xcode’s graphical debugger. If you want to debug both applications at once with the graphical debugger, you’ll have to build them in separate projects.

The Project Directory

When you create a new project, Xcode creates a project directory to hold your project’s contents. The project directory contains the project package, which holds project metadata—as described in the previous section—and user information. The project package has the same name as the project and carries the extension .xcode. For more on the project package, see Project Packages.

In addition to the project package, the project directory can also contain:

• Project files and folders. Source files can live anywhere on your system, but keeping them in your project directory makes it easy to move the project and its contents around. By default, Xcode interprets most paths relative to the project directory.

  You can organize files into any number of subfolders within the project directory. This includes folders for localized resources, as described in Customizing for Different Regions.

  If you create a project from one of Xcode’s project templates, the project directory already contains a number of example source files. For more on the files in a project, see Files in a Project.

• Build folder. When you build a target, Xcode generates a number of files, including the target’s finished product. By default, Xcode creates a build folder in the project directory to hold the files that it creates. The build folder can, however, reside at any location in the filesystem. For more information on the build folder, see Build Locations.