NOTE: This article was first published on Jan 18, 2017. Since that time, I realized I missed one aspect of the project renaming process. Re-read the article or jump straight to the new content.
Sometimes you need to rename your Xcode projects. Not too long ago, this would’ve been problematic. Apple has built a project renaming feature into Xcode, but it’s not good enough for my needs. I’ll show you how I have to go above and beyond the standard functionality to get what I really want. Let’s walk through a concrete example, renaming an Xcode project we’ve been talking about in the post entitled “The UICollectionView is much more than a grid or matrix”.
Easy rename
First, I made a copy of the “UICollectionView – Starter” directory containing the project. In Finder, I right-clicked on the “UICollectionView – Starter” directory and picked “Duplicate”. So now I have a copy of my original Xcode project in a directory named “UICollectionView – Starter copy”.
I then opened the new copy of my project in Xcode 8.2.1. Remember that I have multiple versions of Xcode installed on my Mac, so to open the project I right-clicked on “UICollectionView – Starter.xcodeproj” and picked “Xcode.app (default) (8.2.1)”.
Once Xcode opens up, select the project in the Project Navigator. Your project is represented by it’s name and a little blue icon. You’ll see it on the left-hand, top side of Xcode.
With your project selected in the Project Navigator, go over to the right-hand, top side of Xcode and open up the File Inspector. In the top section (“Identity and Type”), put the cursor into the project “Name” text field. Rename the project from “UICollectionView – Starter” to “UICollectionView – PerformBatchUpdates” and press the [return] key on the keyboard (click to enlarge):
(If you happened to have Finder running, you would’ve noticed that the project file was immediately renamed to “UICollectionView – PerformBatchUpdates.xcodeproj”.)
A dialog box entitled “Rename project content items?” will open up showing two columns: an expanded project file system tree view on the left (“Current”), and proposed project name changes on the right (“Change”). Make sure all check boxes are ticked on the left side and tap on the dialog’s “Rename” button (click to enlarge):
Finally, rename the home/root folder of your project from “UICollectionView – Starter copy” to “UICollectionView – PerformBatchUpdates”. Don’t panic when you build and Xcode tells you:
Missing required module SwiftShims.
PCH was compiled with module cache path [OldPath] but the path is currently [NewPath].
Just delete the /path/to/your/project/UICollectionView – PerformBatchUpdates/DerivedData/ModuleCache directory. NOTE: The path to your “DerivedData” directory can vary. Go to the Xcode menu, then Preferences… -> Locations -> Derived Data to find out where this data lives on your Mac.
You’re done! Project renamed! Move on… but…
Advanced rename
If you’re an advanced developer and want more fine-tuned control, read on.
You may notice that not everything was renamed. If you look at your Project Navigator, you’ll notice that the default, logical (and generally virtual) “group” where all your app’s most important files and bundles are stored — like AppDelegate.swift, ViewController.swift, your storyboard, your asset catalog, etc. — was not renamed. This group was created when you started a new Xcode project.
If you’re a stickler for details like me, you can rename your project’s main file “group”. Pick up where you left off in the “easy” instructions, and, just as before, select the yellow “UICollectionView – Starter” in the Project Navigator and then go over to the File Inspector -> Identity and Type -> Name text field, type “UICollectionView – Core Files”, and hit [return].
Note that this did not rename the corresponding macOS file system directory. To change that:
1) Go into your main project folder in Finder and rename the subfolder “UICollectionView – Starter” to “UICollectionView – Core Files” (don’t panic if you notice files in your Project Navigator turning red — we’re about to fix that);
2) Click on the little folder icon under File Inspector -> Identity and Type -> Location and, when the directory chooser dialog/panel comes up, select the folder you just renamed as “UICollectionView – Core Files”, and tap the “Choose” button;
3) Don’t panic when you build and Xcode tells you that your Info.plist is missing, just go to Project Navigator -> [Your project name] -> Build Settings -> Packaging -> Info.plist File, and change the path’s substring from “Starter” to “Core Files”.
4) IMPORTANT: Delete the /path/to/your/project/UICollectionView – PerformBatchUpdates/DerivedData/ModuleCache directory.
Note that most projects should be organized, having files broken into at least logical groups, and preferably physical directory-based units (like “View Controllers”, “Data Model”, “Collection View Cell”, “Page View Controllers,” “Core Functionality – C++”, “Whatever,” etc.)
5) Finally, you should rename your Xcode project’s “scheme.” When you create a new project as I did for this tutorial, there will only be one scheme. Do some research and find out why you may — and most likely should — have many schemes. The scheme manager lists of all the final products that can be built by your project. For example, you can have schemes to build debug or release versions of your app (“executables”), an “archive” to submit to the App Store (“.ipa”), testing protocols, etc. Notice that after all our renaming, the scheme for this project has not been renamed (click to enlarge):
You need to click on the current scheme and select “Manage schemes…” as shown here (click to enlarge):
In the dialog that opens, rename the scheme to the new project name and then click the “Close” button (click to enlarge):
So now you’ve learned how to rename an Xcode project. Believe me, there will come a time when you’ll need to do it. Come back soon as we continue discussion of making full use of the UICollectionView.
