Overview of an Xcode Project
To carry out the development process, Xcode relies on certain key components. It uses projects to organize these components. The project is a repository for all of the information needed to build one or more software products. It is also the primary workspace for your software development. This chapter describes the contents of an Xcode project and gives an overview of the information required to develop software with Xcode.
In this section:
Components of an Xcode Project
The Project Directory
The Project Info Window
Components of an Xcode Project
A project contains and organizes everything you need to create one or more software products. In your Xcode project, you:
Organize build system inputs for building a product.
Maintain information on items within it 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 1-1 shows a simplified representation of a project and its essential pieces.
Source 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 source files—using Xcode’s built-in text editor or an external editor—and organize files into a target (described next) 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 Projects” describes how Xcode stores these references and discusses the files in a project in more detail.
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.
Executables
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 what program to launch when you run or debug from within Xcode and how to launch the program. The executable environment lets you tell Xcode what command-line arguments to pass, what environment variables to set, what 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. “Defining 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.
Product Information
In addition to the 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 1-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, projectwide symbol searching, and more. Groups and other features for organizing project contents are described in Project Organization; projectwide searches and other features for finding information in your project are described in “Finding Information in a Project.”
Projectwide 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 click the Build button. It also stores the active architecture, which is the architecture for which all products in the project are built.
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. Xcode Source Management Guide 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. “Building for Multiple Mac OS X Releases” briefly describes how to choose a Mac OS X system version in Xcode. For detailed information, see Cross-Development Programming Guide.
Build configurations. A build configuration is a named collection of build settings. You can define different build configurations for different circumstances—such as development or release—and switch between them to alter how the products in a project are built. In this way, you can rapidly try variations on a build. The project defines the list of build configurations; each individual target contains its own definition of the build settings used to build the target with that configuration. See “Build Configuration Overview” in Xcode Build System Guide for more information on build configurations in Xcode.
Active target and build configuration. The active target is the target that gets built when you initiate a build in Xcode. Xcode uses the active build configuration to select the appropriate configuration of the active target and each target it depends upon, when building. See “Setting Build Factors” 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 configuration, 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 be only one active target, one active build configuration, one active architecture, 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.
Renaming Xcode projects: Although you can change the names of the products that project produces (using the Product Name build setting), you cannot change the name of a project.
The Project Directory
When you create a 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 .xcodeproj.
In addition to the project package, the project directory can also contain:
Source files. 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 subdirectories within the project directory, including directories for localized resources, as described in “Localizing Files.”
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 Projects.”
Build folder. When you build a target, Xcode generates a number of files, including the target’s finished product. By default, Xcode creates the build directory in the project directory to hold the files that it creates. The build directory can, however, reside at any location in the file system. For more information on the build directory, see “Build Locations.”
Nonproject files. Nonproject files are files that reside in the project directory but that are not used to build your product. If you use SCM, these files are part or source-control operations made on the project directory. See “Managing Files Under Source Control” in Xcode Source Management Guide for more information.
The Project Info Window
Xcode maintains information about a project at several levels, including project, target, and file. Information kept at the project level comprises general information, project build settings, project build configurations, and project comments. You use the Project Info window to view and edit this information.
To open the Project Info window, do one of the following:
Double-click the project group in the Groups & Files list.
Select the project in the Groups & Files list and click the Info button.
Select the project in the Groups & Files list and choose File > Get Info.
Choose Project > Edit Project Settings.
The Project Info window contains the following panes:
General. This pane contains general project settings that affect all the project’s files and targets. For details, see “General Project Attributes.”
Build. This pane lets you define project build configurations. For more information, see Build Settings and “Build Configuration Overview” in Xcode Build System Guide.
Configurations. This pane contains a list of build configuration names, which may be used by the project and its targets. Build configurations are described further in “Build Configuration Overview” in Xcode Build System Guide.
Comments. This pane lets you add textual notes to the project. See “Adding Comments to Project Items” in Xcode Workspace Guide for more information.
General Project Attributes
Figure 1-3, shows the General pane of the Project Info window.
The General pane contains the following information:
Project identification. Specifies the name of the project and its location. It also identifies the project root, the directory that serves as the root of a project hierarchy. A project hierarchy is made up of two or more projects that share products or resources.
Project format. Specifies the Xcode release with which the project must remain compatible. See “Choosing the Project Format” for details.
Build locations. The location at which the build products and intermediate files for the project’s targets are placed. The options under the heading “Place Build Products In” specify the location where Xcode places the products created when building the project’s targets. The options listed under “Place Intermediate Build Files In” specify where files generated in the course of building the product, but not included in the final product, are placed. See “Build Locations” for more information.
Parallel-target builds. Specifies whether to build independent targets in parallel. To learn more, see “Building in Parallel.”
Base SDK. Identifies the base SDK used to build the project’s targets, which pecifies the minimum version of the operating system to build your product for (you can override this setting at the target level). See “Setting Build Factors” and “Building for Multiple Releases of an Operating System” for more information.
SCM system. Identifies the SCM repository the project uses. See “Connecting to Repositories” in Xcode Source Management Guide for more information.
Source-code indexing. Allows you to rebuild the Code Sense index. See “Code Sense” for details.
© 2009 Apple Inc. All Rights Reserved. (Last updated: 2009-01-06)