Xcode File Tricks
Like this article? We recommend
Like this article? We recommend
Like this article? We recommend
Everyone knows how to add files to Xcode: Select file > Add Files. That simple action is just the beginning of your journey. Do you know the difference between adding and copying files? Do you know how to control the file address so that your project won't get borked when you copy or move it to a new folder? Do you know how to find the original or fix strangely convoluted paths? This write-up introduces essential Xcode file management tricks you need to know. Best of all, it all still works with the new SDK.
Rename Your Project
Every so often you end up regretting a name you chose when building an Xcode project. Fortunately, you're never stuck with your original choice. And, best of all, you don't have to create a new project. When you want to rename your entire project, here's what you have to do.
- Select your project in the File Navigator, as in Figure 1.
- Open the File Inspector, as in Figure 1, (View > Utilities > Show File Inspector).
- In the File Inspector, Edit Identity and Type > Name to the new name (for example, Bill as in "Gates. Bill Gates.") and press Return. Xcode prompts you to confirm, as in Figure 2.
- Click Rename and then click OK. Your project updates and you're all set to continue working. Should you wake up the next morning with a hangover and a vague sense that you just named your project after the founder of Windows, follow these same steps to move your project back to, for example, "Hello World".
)
Figure 1 Select your project
)
Figure 2 Select your project
)
Figure 3 You're ready to start working on "Bill"
Control Your Copying
Each time you add a file to your project, Xcode prompts you (somewhat indirectly) to decide whether you want to create a copy of that file or to add it by reference, as you see in Figure 4. When you check the circled box, Xcode copies the file to the destination group folder.
)
Figure 4 Do you want to copy that file?
If you're working with shared class files used by more than one project, leave that box unchecked. Edits to a copy won't propagate to your master version. So if you find a bug and fix it in the copy, the 99 other projects that use that same code won't get updated. This is typically a bad thing. In contrast, always copy any items that are unique to your project.
So what happens if you copy a file that's already in your project folder but not yet added to your project? Typically, Xcode ignores the copy request and leaves it as-is. (Historically, it created a second copy if the asset was not in the "right" place.)
If you regularly switch between copy and add-reference modes, you might want to check out AddBlocker (download). I wrote this utility so that I could instantly tell if Xcode would copy items. The red apple means "copy," the green apple means "reference." And yes, you can change the current setting directly from the menu bar.
)
Figure 5 AddBlocker provides visual confirmation of Xcode's current add settings
Fix Missing Classes
Have you ever had a problem like the one shown in Figure 6? It happens when you know you've added a class to your project but the linker complains that it can't find it. This situation usually happens when you inadvertently uncheck the Add to Targets check box, shown in Figure 4. The code files are added to your project but not to your target.
)
Figure 6 Add your missing classes back in Build Phases
To fix this problem, select your project and open the Build Phases tab (as in the lower screenshot in Figure 6). Expand the Compile Sources section, and check to see if your missing class is included as a source. If not, there's the source of your problem. Click the + button, select the implementation (.m) file, and click Add. Your build issue should go away.
Pin Down File Paths
Any time you start moving Xcode projects around on your disk, you may encounter the red-colored missing files shown in Figure 7. This normally happens when your file is set to use a path with respect to the project instead of an absolute path. You see this by opening up the File Inspector again (View > Utilities > Show File Inspector). Select any file and the inspector shows you the path it's using for the file.
)
Figure 7 Missing files are a big pain when you move files around
In this example, the Foo folder with its two class files lives on my desk. Before I moved the sample project into its new folder, the project knew to look for these items at /Users/ericasadun/Desktop/Foo. Although it's easiest to fix the missing files problem before you start moving folders around, it's not exactly rocket science to fix them after.
Fixing the Folder After the Move
When you realize that a folder did not travel properly with a project, select the group that represents the folder, as in Figure 8. The arrow points to the heart of the error. The path (../Foo) is no longer valid with respect to the project. To fix this, do the following.
)
Figure 8 Selecting at the granularity where you added items (in this case I added a folder) usually reveals the problem
- Click the little gray folder at the right. A file browser opens.
- Navigate to the actual Foo folder and select it. Click Choose. The file browser closes.
- Change the pop-up from Relative to Group to Absolute Path. As a rule, the current version of Xcode will attempt to create a nonrelative path. This path may contain a few relative elements (such as /Users/ericasadun/Desktop/untitled folder/SAMPLE/../../Foo). With the next step, you can get rid of any relative portions of the path so that your file reference remains robust.
- Click the gray folder again. The browser should still be at the right location, but if it's not, move to the right folder on your system. Click Choose.
At this point, Xcode usually catches up; the Absolute Path matches the Full Path and the two will point to the right place. (Want to make sure? Click the gray circled arrow. It is a Show in Finder shortcut.)
Fixing the Folder Before the Move
To create a portable folder reference, select Absolute Path from the Location pop-up before you move a project. As you'll see, chances are still really good that the absolute path is still using some relative references – especially in Xcode 5.x. You'll definitely want to fix this, as the absolute path will break if you move your project across volumes. (Been there, headdesked that.)
Again, click the little gray folder, select your proper location, and click Choose. The path will update to lose all those relative location dots and your project is good to go.
Wrap-Up
The File Inspector utility pane is one of the most useful and possibly the most overlooked of all Xcode's features. Although it deserves a lot more love and coverage than this short write-up can offer, hopefully you'll have had a taste of its power and how it can help you manage your Xcode projects for less frustration down the line.