The Path and Path Type fields define the item's reference, and are what most of this chapter has been about so far. The Full Path field displays the ultimate (resolved) path to the file or folder. This is how Xcode interprets the path using the given reference type. You can change the reference type using the pop-up menu. Xcode recalculates an equivalent path.

To change the path, click the Choose button. Select a file or folder from the browser. For file, folder, and framework items, the name of the item changes to match that of the newly selected file or folder.

The next section in the Info window is the item's type. This is an internal categorization based on the file's file type and extension so that Xcode knows how to treat the item. It is used to determine whether an item can be included in a target, and in what phase of the target the item should be. It determines how, or whether, Xcode will display the item in an editor window and what language and syntax coloring should be used.

You can change how Xcode treats an item by selecting a different type. Normally Xcode sets the type correctly, but on rare occasions you might need to change it if, say, Xcode identifies a file as being text.xml when it's actually text.plist.xml. The type attribute only affects Xcode's handling of the file. The operating system, external build systems, and compilers still interpret the file based on its type and extension. That is, changing the type of an .m file from source.c.objc to source.c.cpp will not cause the file to be compiled as a C++ file.

The File Encoding, Line Endings, and Tab attributes apply only to text files and are disabled for all other types. The File Encoding defines the expected binary format for the characters in the file. Change this setting if the assumption is wrong. The Line Endings attribute is also an assumption, but one that is largely superfluous; most Xcode editors determine what line endings are being used when the file is opened.

Changing the File Encoding for a text file presents the dialog box shown in Figure 5-6. The Convert button interprets the file using the previous encoding, and then rewrites the file using the new encoding. Use this option if the encoding of the file was correct and you want to change the format of the file to a different encoding. The Reinterpret button simply changes the encoding attribute in the source item, leaving the file unaltered. Select Reinterpret if the encoding attribute of the file was incorrect, and you're changing it to what it should be.

The Tab Width, Indent Width, and Editor Uses Tabs options (see Figure 5-5 again) are explained in the next chapter. Normally, you will want to use the same settings for all files, but you can change them for an individual file here, or by using the View

Figure 5-6. FIGURE 5-6

The Make File Localizable and Add Localization buttons are used to create multiple, locale-specific versions of a file. Many files can be localized so that language- and location-specific information in the file can be customized for different regions and populations. File localization is also covered in the next chapter.

In Chapter 3, you learned how to use the Inspector palette or an Info window to display the aggregate attributes for multiple items. Settings that are common to all of the items are shown. If all of the items have the same value for a particular setting, that value is displayed. If a value differs for some items, the value displayed is some kind of Mixed value, as shown in Figure 5-7. For check boxes, this displays as a dash. Changing any of the settings in a multi-item Info window changes that setting for all of the items to the same value.

Figure 5-7. FIGURE 5-7

Some settings behave a little differently when they are changed for multiple items. This is particularly true of the Path attribute. You wouldn't want Xcode literally to set the same path attribute for multiple items; all of the items would suddenly point to the same file or folder! Instead, the Choose button in a multi-item Info window enables you to choose the folder that contains all of the items. The name of each item is not altered, and a new path for each is constructed by combining the chosen folder and the item's file or folder name. This is an efficient way of setting the location for any number of source files at once. Note that this can cause item references to be broken if the folder chosen does not contain one or more of the items.

You use this ability of Info windows later in this chapter to reorganize some large projects and fix the properties of targets.

In Chapter 3, you created, renamed, and deleted source groups. You then moved groups around and moved source files into and out of groups. If you used what you've learned in Chapter 3 to create the example project shown in Figure 5-8, you would end up with a project folder that looks like Figure 5-9.

Figure 5-9. FIGURE 5-9

In Chapter 3 you were probably unaware that every group you created had a folder reference. The InventoryServer.m file is relative to the folder referred to by the Services group, which is relative to the folder referred to by the Classes group, which is relative to the folder referred to by the Root project group. You can see this by examining any source item's reference.

Now you know that all of these source items and groups use enclosing group references, which mean they all indirectly refer to the project folder. This is why all of the files are in the same folder (see Figure 5-9).

Whenever you create a new group using the File

Thus, the default organization of Xcode projects places all of the source files directly in the project folder. You are free to reorganize the hierarchy of your source groups and items to any depth you want; the organization of the actual files will remain flat. For small- to medium-sized projects that are self-contained and have no duplicate filenames, this is the easiest organization. It is uncomplicated and shouldn't cause any surprises. Better yet, you don't have to worry about source group folder references. If your project falls into this category, feel free to skip ahead to the next section now and come back here when your projects get more complex.

However, if you want to control the physical organization of the files in your project, or your project source files are already organized into multiple folders, read on.

Often, source files are already organized into a hierarchy of folders. They may have been organized this way in a former project, for source control, or by an obsessive programmer — we know who you are. The next few variations of the Root project present different techniques for grafting a source group structure onto an existing folder structure.

Figure 5-10 shows a reorganization of the source files by type. All of the programming source files in the Root2 project have been moved into a Source folder and the application bundle resource files have been moved into a Resources folder.

Figure 5-10. FIGURE 5-10

The folder references for the Classes, Other Source, and Resources groups were changed from enclosing group to project relative. The paths of the first two groups were both set to Source. The Resources group's path was set to Resources.

This is a variation of the default references you looked at in Root. Instead of lumping everything together in the project folder, a few key folders are designated as gathering places for a broad collection of assets. The Source folder contains all of the program source files. In the project, the Classes, Services, Client, and Other Sources groups all refer to the same folder. This allows fine-grained organization within the project structure group, using a coarser folder structure.

This is a good organization for a medium-sized project whose files are grouped by type, where you just want to keep the main project folder uncluttered, or there is some other logical reason for subdividing the files. A good application of this approach would be for a project that produced multiple targets (that is, a client and a server). The project might have broad subfolders like Common, Client, and Server, whereas the project structure group would have more detailed groups, like Utilities, Network Services, Logging, Database, and so on.

By establishing a few key high-level groups anchored to a specific subfolder, then using default subgroups, you keep much of the flexibility of Xcode default source group arrangement, while imposing a modest amount of structure on the actual files.

Another approach is to mirror the structure of a complex hierarchy of folders in the project group. Rather than being disconnected from the folder structure in the filesystem, the project source groups mimic them verbatim. This is a good solution for large projects with an extensive folder hierarchy. The folder structure in Figure 5-11 isn't that large or extensive, but the technique applies to a hundred folders as easily as it applies to these six.

Figure 5-11. FIGURE 5-11

In this scheme, each source group uses its path to point to a specific subfolder within its enclosing group's folder. In earlier projects, all of the source groups using an enclosing group reference type have had empty paths — referring to the same folder as their parent group. These groups all have paths that refer to a subfolder of the enclosing group and have the same name as the folder to which they refer. The end result is a source group structure that parallels the folder structure in the filesystem.

In Figure 5-12, the Source group refers to the Source folder within the folder of its enclosing group. Its enclosing group (Server) refers to the Server folder within its enclosing group, which is the project folder.

Figure 5-12. FIGURE 5-12

A few of the source items in the Root3 project are listed in the following table to illustrate the relationships.

As you develop the project, it's pretty easy to maintain the relationship between the source groups and the filesystem folder structure. New and imported files are automatically added to the correct folder. If a folder is reorganized or renamed, making the same change to its source group keeps all enclosing references valid.

You might think that setting up all of these references would be tedious — especially for the imagined project containing hundreds of source files. Fear not. Xcode's import process, described a little later in this chapter, will create any number of nested source groups — exactly like those described here — with a single command.

Conveniently, all of the references so far have been to folders inside the folder of the enclosing group or project, but this does not have to be the case. Figure 5-13 shows the project group and the files in project folder for Root4.

Figure 5-13. FIGURE 5-13

You'll notice that the project includes a Client group that contains two source files (WarehouseClient.h and WarehouseClient.m) that aren't in the project folder, so where do these files come from? The answer can be found in the Client group's properties, as shown in Figure 5-14.

Figure 5-14. FIGURE 5-14

The Client group uses a project relative reference. Its POSIX path refers to a subfolder of Root4's sister project, Root3. The Root4 project has included files outside its project folder, just as if it owned them. Some selected source item references are listed in the following table.

Although it's easier to create a single project with multiple targets, as you see in Chapter 16, this isn't always possible. If you must create multiple projects that need to share common assets, relative paths that refer to sister project folders is one way to share a single source file.

A popular use for this scheme is to set up "libraries" of source files (that is, a Utilities folder full of commonly used C functions or classes). Any number of projects can include selected files from the shared Utilities folder, without duplicating source files, or incurring the added complexity of creating a formal framework or dynamic library.

This technique can also be used to create "shell" projects. Suppose you have a large project written for Linux in an Eclipse project folder. You can create an Xcode project that uses source group paths that refer to the folders inside the Eclipse workspace folder. The Xcode project wouldn't have to contain anything beyond the project document and any project-specific files.

The disadvantage to this technique is that it creates a rather fragile project structure:

Ideally, project folders are self-contained and autonomous. The only references they have to assets outside the project folder are to system frameworks that never change location. When the ideal isn't practical, you can use relative paths to include shared assets outside the project's folder.

It's just as important to know what kind of references you should not create. I left this last project open overnight, and some mischievous pixies snuck in and decided they would have a little fun with it.

At first glance, the RootRot project looks pretty much like project Root3. All of the references are valid, and the project builds and runs — at least on my computer. Things can't be all bad, can they? The following table lists a few of the references in the project.

Here's some of what's going on in the RootRot project:

Although Xcode provides you very flexible structures for organizing and referring to your project's assets, you can see that this flexibility can be abused. If you checked out a project like RootRot to a new directory, you'd probably end up spending more time trying to figure out what's wrong with the project than you would building it.

Here are some simple tips for keeping your project group functional and tidy:

You have basically two ways of selecting the items to add to your project: start in Xcode or start in the Finder.

The first is to use Xcode's Project

Figure 5-19. FIGURE 5-19

The second method is more direct. Select any group of items in the Finder (or any application that lets you drag files) and drag them into the source group of your project. A drop indicator shows you where in the source group the new item, or items, will be created — exactly as it does when you're dragging items around in the tree.

The only significant disadvantage of the drag-and-drop method is that Xcode permits you to create duplicate items to files that are already referred to in the project.

As soon as Xcode knows where to create the new source items in the project and what files will be used to create those items, it presents the dialog box shown in Figure 5-20.

Figure 5-20. FIGURE 5-20

This dialog box contains several controls that determine what kind of source items are created, the type of references they will have, and where the final source files will reside. The effect of these options is often interconnected; some options behave differently depending on the choices you make for other options.

Xcode has a special interface just for adding frameworks. Right/Control+click the source group where you want the framework added and choose the Add

Figure 5-21. FIGURE 5-21

Xcode assembles a list of all known frameworks and libraries. Choose one or more from the list and click Add. If you're having trouble finding what you're looking for, the pop-up menu at the top will narrow the list to a specific class of library or framework.

To add a framework that isn't one of the standards, use the Project

Xcode can open an arbitrary file into an editor window. The file does not have to belong to a project. You can add the file of any open editor window to the current project by selecting the Project

It is very easy, when you're adding lots of new source files to a project, to end up with files in targets where they don't belong. This most often happens when you're adding source and header files at the same time. Targets that compile C source into object files (native targets) normally only accept C, C++, or Objective-C source files. Trying to add the companion header files to those targets at the same time does nothing, but some native targets have a Copy Files phase that accepts any kind of file. The end result is that all of the .h files get added to the target's Copy Files phase, and the target dutifully copies all of the headers files in your project into the final application. This is probably not what you want.

To fix this, select the project structure group in the Groups & Files list to display all of the files in the project in the details window (choose View

You can adapt this technique to make similar changes in other types of files.

The ReorganizeMe1 project, shown in Figure 5-24, has two subfolders: Main and Flipside. You decide that the SpinningWidget class files need to be moved from the Main group to the Flipside group.

Figure 5-24. FIGURE 5-24

To relocate the two files, follow these steps:

Whenever you move a source item, Xcode adjusts the path (never the reference type) of the item so it continues to refer to the same file or folder. This is convenient in one sense, because it allows you to reorganize your source items freely without breaking any references. The disadvantage is that it permits you to create convoluted item references with relative paths through parent folders and an organization that no longer reflects the organization of the physical files.

All of the items in this exercise use enclosing-group references. When you moved the two source file items from one group to the other in step 2, Xcode recalculated new paths starting from the new group back to the old one's folder. If you had stopped and looked at the attributes of the two items after step 2, their paths would have been ../Main/SpinningWidget.h and ../Main/SpinningWidget.m. This also explains why the two items were still valid after the move.

In step 4, you moved the actual files. As a result, the files were no longer in the Main folder and the source item references broke. When you switched back to the project window, Xcode displayed the two items in red.

In steps 5 and 6, you examined the attributes of the two items in a multi-item Info window and used it to point both items to their respective files in the Flipside folder. Remember that when you select a new path for multiple items, you're selecting the parent folder for every individual item — you're not setting every item to the same path. The path for each was recalculated using a relative path to the Flipside folder (which is nothing, because the enclosing group's folder is the Flipside folder) and their respective filenames. The references are once again valid.

Now you are going to relocate entire folders. This demonstrates the principle advantage of using enclosing-group references in your project.

ReorganizeMe2 has a Source folder that contains two subfolders: Product and Order. The project is about to grow into a client and server. The source files for the client and server are to be kept apart, and the common code moved into a shared tree. Follow these steps:

The Order and Product source groups refer to the Order and Product subfolders in their enclosing group's folder. Moving the Order and Product folders into the newly created Common folder broke the references to those folders, and all the references of the items they contained.

In step 3, the new groups Common, Client, and Server were created with enclosing group references that referred to the folder in the source group (remember that this is the default for all newly created source groups). Although the Order and Product groups are now enclosed in the Common group, they still indirectly refer to the same location and are still broken.

In step 4, you changed the Common group's folder from the Source folder to the new Common subfolder. As soon as that happened, the references in the Order and Product folders were valid again.

Step 5 simply prepared the other two groups, Client and Server, so they reference files in their respective folders.

When you're using enclosing-group references, it is usually easier to rearrange folders than it is to move individual files around. Xcode only adjusts the path of the group being moved. Items within that group are not adjusted and continue to have the same relative relationship to their enclosing group. After the parent group references are fixed, all of the child references are valid again.

You can see how using the multi-item Info window and relative references can save a lot of time when changing references for large trees of groups and files. If you're moving just a few folders around, that's probably the best way, but even this can be a fair amount of work if you're making a lot of changes at once.

Another technique is simply to throw the whole thing away and let Xcode rebuild all of the relationships from scratch. Start with the ReorganizeMe3 project. All of the items in this project have enclosing-group references.

ReorganizeMe3 has several subfolders: Database, Product, Order, ShoppingCart, and Utilities. Create three new folders in the Source folder: Common, Client, and Server. Move the Database folder into the Server folder. Move the ShoppingCart folder into the Client folder. Move the Product, Order, and Utilities folders into the Common folder. The file structure should now look like Figure 5-25.

Figure 5-25. FIGURE 5-25

Now follow these steps:

Remember that the project document doesn't contain any of the source material for your project; just references to those files. In step 2, you deleted all of the references to the source files in this project — but just the references; the original source files are still in the project folder.

In steps 2 and 3, you used the Add to Project command to re-create new groups and source file items that match the reorganized folder hierarchy exactly.

If you have major asset reorganization to do, the fastest and easiest way to rectify your groups and source items might be simply to start over. This might inadvertently include other files, or place files in targets that don't belong there, but these aberrations can usually be dealt with swiftly.