Files in Xcode

For each source file included in a project, Xcode tracks file attributes, such as the name and type, as well as other information. Figure 3-1 shows the information that Xcode tracks for source files.

In the illustration, the name is the file-system name for the file. The file type identifies the file as being one of several classifications (source file, image file, text file, and so on.) Depending on the file type, Xcode stores additional information about the file, such as the file encoding, type of line endings, and so forth.

The path to the file specifies the file-system location for the file. The path type —which you can modify—indicates how Xcode stores the path; that is, whether it is absolute or relative to the project directory or another location. How Files Are Referenced describes the various ways in which Xcode stores paths.

You can view and edit these file attributes in the File Info window.

The Files in a Project

The project lets you pull together all of the files and other information required to build a set of related software products. Within a project, you use a target to specify the files needed for an individual product. The files can reside at any location in your file system; they do not need to be placed in your project folder. A project can contain:

• Source files. A source file is any file that Xcode uses in building a target, including source code files, resource files, image files, and others. For files you need direct access to in Xcode—for example, files you want to edit using the Xcode text editor—you should explicitly add a reference to each file to the project. This includes source code files you want Xcode to compile.

• Folders. If you have a folder of files that you manipulate as a whole—such as a folder of help files—you can simply add a reference to the folder to your project. This allows you to manipulate the folder in Xcode instead of touching each file individually. (To access any of the files individually from Xcode, you must also add a reference to the file to your project.)

• Frameworks. You can add a reference to each of the frameworks that your product links against. This gives you easy access to the framework’s headers, directly in the project window.

When you create a project using Xcode project templates, described in Choosing a Project Template, Xcode populates the project with a small set of default files required to build the associated product. For example, Figure 3-2 shows the contents of a project created using the Cocoa Application project template. The project contents have been expanded in the Groups & Files list to display its contents in outline view. Keep in mind that the contents of a project vary depending on the project template and the products it creates.

The example project contains the following items:

• The Classes and Other Sources groups contain source-code files.

• The Resources group contains resource files for the application. This includes the main.nib file that defines the user interface, the Info.plist property list file, and the InfoPlist.strings files containing strings used in the interface.

• The Frameworks group contains references to the frameworks that define the system interfaces used by the application’s code. You can view a framework’s header files by disclosing the contents of the framework in the Groups & Files list.

• The Products group contains references to the products created when the project’s targets are built. A special type of file reference, called a product reference, refers to the build system output for a particular target. A product reference lets you view your target’s products right in the Groups & Files list. You can use the product reference to refer to the product in the same way you use a file reference to refer to a project file. Note, however, that the product reference does not actually refer to anything until you have built that target.

To learn more about the Groups & Files list, see Project Window Components.

Xcode keeps a reference to each file, folder, and framework you add to your project. Through these references Xcode finds your files directly when it builds a product. Xcode also provides build settings for specifying general search paths for various items, such as headers and libraries. These include the Header Search Paths, Library Search Paths, and Framework Search Paths build settings.

Managing Files and Folders in a Project

If you created a project using one of the project templates or if you converted an existing project, your project already has a number of groups with files, folders, and product references. At some point you may need to add or remove files or folders from a project. The following sections show how to accomplish these tasks.

Adding Files and Folders

There are two ways for you to add files or folders to your project:

• In the project window Groups & Files list, select the group to add the files to, and choose Project > Add to Project.

  Use the resulting dialog to navigate to and choose the file or files to add. If you want to add all of the files in a given folder, you may simply choose the folder. The files or folders you add are placed after the items currently selected in the Groups & Files list, if any.

• Drag the icons for the files or folders from the Finder to the project window Groups & Files list. A line shows you where the files will be added.

As a shortcut, you can add a file that is open in an editor window to the project by choosing Project > Add Current File to Project

The editor window must have focus.

After you have selected the file or files to add to the project, using either of the two methods described earlier, Xcode displays a dialog, shown in Figure 3-3, that allows you to specify how the files are added to the project.

Here is what the dialog contains:

• The “Copy items into destination group’s folder (if needed)” option controls whether or not the files are copied into your project folder on disk. If you select this option, Xcode copies over any files that are not already present in the project folder. If the project folder contains subfolders for groups, then the files are copied into the appropriate subfolder.

• The Reference Type menu specifies how the location of the file is stored. For a description of the reference styles available to you, see How Files Are Referenced. Note that this menu does not contain any source paths until you have defined one or more source trees in Source Trees preferences (for source-tree details, see Source Trees). After you have defined a source path, it appears at the bottom of the Reference Type menu and you can choose it for the files and folders you add.

• The Text Encoding menu specifies the encoding for the file or files. This is the character set that Xcode uses to display and save a file. For more information on file encodings, see Choosing File Encodings.

• The Add To Targets group allows you to add the file to one or more of the targets currently defined in your project. If the checkbox next to a target name is checked, the file is added to that target when it is added to the project. When you add a file to a target, that file is built when the target is built. You can specify which files are included in a target at any time; this option allows you to add the file to your project and to any necessary targets in one step.

The remaining options apply only if the selection of files to add to the project includes one or more folders. Xcode can add folders in two ways, as a group or by folder reference.

• Group. Xcode recursively creates groups for the folder and its subfolders. Each of the files in these folders is added to the project and is placed in the group for the appropriate folder. If you choose to copy the files into the project’s folder, Xcode duplicates the folder hierarchy. If you move a file to the folder outside of Xcode, Xcode does not add the file to the project.

  To add a folder as a group, select “Recursively create groups for any added folders.”

• Folder Reference. Xcode adds the folder itself to the project but not its contents. This is useful if you need to manipulate the folder as a whole but not the individual items within it. One example is a folder of help files that you edit outside of Xcode and that you want Xcode to move into the application’s Resources folder when you build the application.

  To add a folder as a folder reference, select “Create Folder References for any added folders.”

Renaming a Project

When you create an Xcode project the name you choose for it is replicated in several files within the project directory, including the project package (see The Project Directory for information about the project package), source files (such as application-delegate source files in Cocoa-application projects), info-plist files, and the built product. Other than having the project name within their names, the files do not have a structural relationship with each other. That is, changing the name of the project package does not result in a change to the name of built product. Therefore, renaming a project in a satisfactory way requires a set of very focused changes. Xcode’s project-rename command changes the name of a project and attempts to effect that change in the appropriate build settings, targets, and files.

To rename a project, choose Project > Rename.

When you rename a project, Xcode renames all targets that contain the old name. As part of renaming a target, Xcode renames prefix, info-plist, and product files.

Figure 3-4 shows a project named Prototype with two targets containing that name. The files that also contain “Prototype” in their name are highlighted in the detail view.

When you execute the project-rename command, Xcode displays the project-rename dialog, shown in Figure 3-5. This dialog lists the items over which the rename operation takes place; you can deselect items you don’t want renamed. The dialog also lets you indicate whether to create a snapshot before renaming the project. You can later examine the snapshot to get a list of the files Xcode modified as part of the operation. For more on snapshots, see Snapshots.

Figure 3-5 shows the project after Xcode completes the rename operation. Note that not all the files with “Prototype” in their name are renamed.

After Xcode completes the project-rename operation, you should review all aspects of your project to ensure that the operation was completed as expected and to complete the task in places that Xcode did not modify but that should be updated, such as user-interface elements.

Keep in mind that project templates use build settings to propagate the value of properties, such as the product name, throughout the project. For example, an application’s info-plist file uses the value of the Product Name build setting to define the application’s bundle-name and bundle-identifier properties. When the info-plist file contains template-based definitions for these properties, changing the value of the Product Name build setting updates the values of those properties accordingly. However, if the properties have been customized by removing PRODUCT_NAME from their definitions, renaming a project does not change the value of those properties.

Linking Libraries and Frameworks

Each of your project’s targets specifies the frameworks and libraries against which its source files are linked. You can link against standard libraries or external libraries. Standard libraries or frameworks are those provided by the active SDK. External libraries or frameworks are those not provided by the active SDK.

To add a library to a target:

1. Open the Info window for the appropriate target and click General.

   The Linked Libraries list in the General pane lists the libraries against which Xcode links the target’s source files.

   

2. Click the Add (+) button below the Linked Libraries list.

3. Choose the library to add.

   To add a standard library, choose the library from the dialog.

   

   To add an external library, click Add Other.

   After choosing an external library, Xcode presents the same options described in Adding Files and Folders. The following options apply to external libraries:

   • The Reference Type menu in the dialog specifies how the location of the framework is stored. For a description of the various reference styles available to you, see How Files Are Referenced.

   • The Add to Targets group box allows you to add the library to one or more of the targets currently defined in your project. If the checkbox next to a target name is checked, the library is also included in that target when it is added to the project.

   • The Text Encoding menu specifies the encoding used for the files in a framework. For more information on file encodings, see Choosing File Encodings.

4. Choose whether the library is required or optional.

   Required libraries must be present on the host computer for the product to load. Optional or weak-linked libraries may or may not be present for the product to load; however, before accessing any of the library’s symbols at runtime, you must ensure that the optional library is present on the host.

In addition to the Target Info window, you can use the detail view to view the libraries your product links against:

1. In the Groups & Files list, reveal the target’s build phases.

2. Select the Link Binary With Libraries build phase.

   The detail view shows the libraries your product uses. The Role column indicates whether the library is required or optional at runtime.

Source Trees

A source tree is a root path that can be used to define a common location for target outputs. A source tree defines a name and a location on the local file system. When you add files and folders to your project, you can specify their location relative to any source tree defined for your computer. Xcode stores the file reference relative to this source tree. Any users who have the same source tree defined are able to work on the same project seamlessly, provided that the file also exists at the source tree location on their computers.

Source trees let you keep common resources in locations other than the project folder of an individual project and still transfer projects back and forth between team members and their various computers without breaking the project’s file references. This is particularly useful if you have a set of common files or resources that are used in a number of projects and therefore cannot live in the project folder. Everyone working on a common project should have the same source trees defined; even though the locations assigned to those source trees may differ, the names must be the same in order for Xcode to locate the necessary files and materials on the developer’s computer.

The source trees that you define are available to all your projects; that is, Xcode supports CodeWarrior-style global source trees. Because source trees are stored for each user, if you have multiple developers using a single computer, you will have to define the source trees for each user, even though the location for those source trees is the same. After you have defined a source tree, it is available to you from the Add Files dialog to use when adding file, folder, and framework references to your project. You can also select the source tree from the Path Type pop-up menu in the File Info window, described in Viewing File Information.

You can edit source trees in Source Trees preferences. To open this pane, choose Xcode > Preferences and click Source Trees. To add a source tree, click the plus (+) button beneath the source tree table. Xcode adds an entry in the table. Add the following information to the entry:

• Setting Name is the name of the source tree. This name must be the same for all users who wish to use this same source tree to refer to common files.

• Display Name is the name that Xcode shows for the source tree in dialogs, Info windows, and anywhere else the source tree is used in the user interface. For example, this is the name used in the Path Type menu of the File Info window.

• Path is the full path to the files and other resources located using this source tree on the user’s system. This path may vary from computer to computer, and from user to user.

To delete a source tree, select the source tree in the table and click the minus (-) button. To edit a source tree, double-click the entry for the source tree in the appropriate table column and type the new text.

Referencing Other Projects

In addition to file, framework, and folder references, Xcode projects can contain a cross-project reference; that is, they can refer to another project outside of the current one. It is not always feasible or desirable to keep all related targets and products in a single project. However, you may still need to reference targets or products that reside in a different project. For example, you may have several applications that rely on a common framework that resides in a different project. In this case, you can add a reference to the project containing the framework to the project containing the application. This reference, called a cross-project reference, lets you access the targets and products of the referenced project from your current project.

To create a reference to another project, choose Project > Add to Project and select the project package (the .xcodeproj file package) of the project you wish to reference. (You may also drag the project group in the Groups & Files list of another project or a project package in the Finder to the current project’s project group.) Xcode adds a reference to the source group for your current project, visible in the Groups & Files list. The project reference is identified by the Xcode project icon. Clicking the disclosure triangle next to the project reference shows the product references that the other project contains. These product references can be added to targets in the current project.

You can relate targets in the current project to targets in the referenced project by creating a target dependency. You can add a dependency on a target in the referenced project in the same way that you would add a dependency to a target within the same project. See Adding Target Dependencies to learn more about target dependencies.

For projects that use cross-project references, you should use a common build location; doing so ensures that Xcode can automatically locate products created by targets in those projects. For more on build locations, see Build Locations.

The Xcode Cache

Xcode places its persistent caches in a secure location in your file system. You can get to this location using the getconf command:

> cd `getconf DARWIN_USER_CACHE_DIR`

This location is known as <Xcode_Persistent_Cache>.

If the Xcode cache grows too much, you can delete it using the Empty Caches command. Keep in mind that the Xcode cache may include precompiled headers for your projects, and building those projects may take longer after the cache has been emptied.

To empty the Xcode persistent cache, choose Xcode > Empty Caches.