WHAT'S IN THIS CHAPTER?
Creating a project and defining where it's stored
Choosing the right project template
Juggling multiple projects
Configuring project-specific properties
Now that you can navigate around the Xcode interface and customize its view, it's time to learn how projects are created, stored, opened, and closed.
Every project has two essential parts: the project document and the project folder. The project document, Simple.xcodeproj in Figure 4-1, contains all of the structure, references, layout, settings, preferences, and other attributes that define the project.
The folder that contains the project document is the project folder, in this case the Simple folder. This is the root location for the project. The project document and project folder usually have the same name, but that's not a requirement, and a project folder can contain multiple project documents.
You create a new, empty project using the File
"Empty" is a bit of a misnomer. The New Project Assistant creates a new project using one of the many project templates that are built into Xcode. The project it creates will be far from empty, and may actually have quite a lot in it before you even begin. The templates try to provide the basic framework — a main() function, an empty subclass of NSDocument, a menu bar with all the standard items, required driver entry points, scores of build settings, and so on — all appropriate to the type of project you are creating. The templates also include the libraries and frameworks a project of that type is expected to need. Some templates go the extra mile and include libraries and frameworks that you're just likely to need. These frameworks are referred to by the project, but are not members of any targets. Being included in the project already, it's a trivial matter to add them to a target; this is quite a bit easier than being forced to identify and add the framework yourself.
The Xcode templates give you a huge head start in getting your project going, because so much of the basic groundwork is already done for you. In fact, most projects will build and run (albeit lacking any real functionality) as soon as they are created. Remember that there's nothing done by the templates that will lock your project into a particular technology or configuration. Any project can be modified to produce any other project. You can obtain the same result by starting with an empty project and configuring it appropriately, it's just a lot more work.
The first step in creating a new project is to choose the template that most closely matches the type of program or product you want to create. The templates are organized into broad categories on the left. Start by selecting a category, say Mac OS X Application, and a list of project templates appears in a panel on the right.
Many templates include additional options for refining the kind of project you want to create. The Cocoa Application template asks whether your application will be document based, will use Core Data for storage, and whether you plan to include a custom Spotlight Importer plug-in that will integrate your application's data with the Spotlight search facility. The options you choose influence what classes, boilerplate code, and targets are included in your new project.
The Command Line Tool project, pictured in Figure 4-3, has a completely different kind of question. It wants to know in what kind of language you plan to write your command-line tool. The choice here will determine what kind of source files are initially added (C, C++, Objective-C), what headers it will include, and with which frameworks it will link.
If you have no idea where to begin, you might want to read more about the kinds of programs you can develop for Apple platforms at http://developer.apple.com/gettingstarted/. If you're also working through a programming tutorial, say on iPhone development, the tutorial should indicate which template to choose.
After you have selected a project template, click the Choose button. A save dialog box appears prompting for the name and location of the new project. The location you choose determines where the new project folder is created. Inside the newly created project folder, Xcode creates a project document along with whatever additional source files and folders the template defines. This might be a single file or twenty.
The project document and folder will have the same name. Choosing an existing project folder for the location just creates a new project folder inside the existing project folder. If you want to have multiple projects share the same project folder, create a new project outside the existing one, then manually migrate the contents of the new project into the existing one.
Warning
It's possible to "overwrite" a project by creating a new project with the same name and location. In this situation, Xcode warns that you are replacing an existing project. It then proceeds to create new files inside the existing project folder, warning you about template files that will overwrite existing ones. I wouldn't recommend trying this, because the benefits are dubious and it's hard to predict what existing files would be overwritten.
The project's name does more than just name the project folder and document. Your new project is customized in numerous places with the name you give the project. The easiest explanation is an example. Say that you are excited about creating a new Xcode project, and your exuberance influences your choice of project names, as shown in Figure 4-4.
The project folder and documents were created from the iPhone OS, Tab Bar Application template. Looking at the project contents, shown in Figure 4-5, you find some rather convoluted names.
The project, shown in Figure 4-5, contains a class named Wow__My_first_tab_bar_iPhone_AppAppDelegate. You might be happy living with the goofy application and target names, but really long class names like this will eventually be awkward. You have two choices: You can refactor the class names to something more reasonable, or you can throw the project away and try again.
When creating your project, consider what else you are naming, and what you might want to rename. Ultimately, the name of your project should describe what it produces. I recommend naming your project after the application it produces, and then fixing up class and filenames as needed.
Beyond just using the project name to customize file and class names, Xcode uses a number of other values to fill in variables in the project template. Similar substitutions are performed when creating new project files.
If you've created a few projects or files already, you've probably noticed the author credits that get inserted at the beginning of each source file, as shown in Figure 4-6.
The comments include today's date, your name, and a copyright statement that includes your company's name. The company name will either be your company's name or the placeholder __MyCompanyName__.
Xcode gets your name from your user account information. It obtains your company's name, rather cleverly, from your address book. If the company name in new projects is incorrect or missing, here's how to fix it:
Open the Address Book application.
Locate your address card, or create one for yourself if one doesn't exist.
Fill in the card's Company field, if empty.
Select the card in the Name column and choose the Card
The address book identifies a single card as being "you." You can jump directly to this card using the Card
Older versions of Xcode would obtain your company's name from an obscure ORGANIZATIONNAME macro stored in Xcode's preferences file, which had to be edited manually. Thankfully, those days are behind us.
To close a project, close the project window or choose Close Project (Control+Command+W) from the File menu. Changes made to the project's structure or attributes are always immediate, so there is no confirmation dialog box asking whether you want to save the changes to your project. However, if any source files in the project have been modified but not yet saved, you are prompted to save or discard the changes made to those.
Closing a project closes all of the windows associated with that project. Windows that contain project content (editor windows, the build window, the Class Browser, and the debugger) are all closed along with the project window. Generic utility windows (Activity Viewer and Help) that do not apply to a particular project remain open.
To reopen a project, open the project document in the Finder, choose the project from the File
Two Xcode preferences, both in the General tab, affect how and when projects are reopened:
The Reopen Projects on Xcode Launch option automatically reopens projects that were open when you last quit Xcode.
The Restore State of Auxiliary Windows option restores the position and size of all the windows that were open when you closed the project. Without this option, only the project window is reopened and any new windows open at default positions on the screen.
You can have several projects open simultaneously, but Xcode focuses on only one project at a time. Whenever a project window, or any project-specific window, is the front (active) window, that project becomes the active project. Commands that act on a project, which include most of the commands in the Project, Build, and Debug menus, apply to the active project. You can (usually) tell which project is active by looking at the Window menu.
The Window menu in Figure 4-8 shows two projects — LogInLogOutNotificationTest and Sketch — open at the same time. All of the windows belonging to the LogInLogOutNotificationTest project are listed immediately under the project's name. This includes the project window itself and the main.c source file being edited in a second window. Note that if you are editing a file in a pane of the project's window, the name of the project window changes to that of the file, followed by the project name. Therefore, the title of the project window may or may not be the name of the project, depending on its state.
The check mark in the Window menu indicates that main.c is the currently active window and, by inference, LogInLogOutNotificationTest is the currently active project. Selecting a window from the menu brings it to the front, making it, and its project, active. Selecting the name of the project itself brings that project's window to the front.
If the front window does not belong to any project, such as a window containing documentation or the Activity Viewer, things can get a little confusing. Some windows cause Xcode to disable all project-specific commands. In effect, no project is active until you switch back to a window belonging to one of the open projects. Other windows, like the documentation browser, don't alter which project is active, but also don't indicate which project was active, so it's impossible to determine easily which project is still active. You might also become disoriented when editing a source file that is shared by two projects. A window belongs to the project you used to open the window, even if the file in that window is part of another project that is also open and active. When in doubt, activate the project window before starting a build or debugging session, or simply keep windows belonging to other projects closed when they are not the focus of your development.
You can easily rename the project folder or the project document after the project is created. To rename either, first close the project. In the Finder, rename the project folder or project document. Do not alter or remove the .xcodeproj suffix of the project document. Reopen the project by opening the project document. The Project Structure Group in the Groups & Files list will reflect its new name.
The folder containing the project document is always the project folder. Moving a project document to another folder implicitly changes its project folder.
The reason this may be significant has to do with the way in which references to source files are kept. References to files used in your project can be relative to the location of the project folder. There are also other kinds of references, all explained thoroughly in Chapter 5. Changing the name or location of the project folder may affect these references.
Moving the entire project folder to some other location is the safest relocation possible. This only breaks the project if it contains project-relative references to items outside the project folder, or absolute references to items inside the project folder. Both of these conditions are unlikely.
Moving the project document to some other location can be hazardous. The most significant thing this does is change the project folder. Absolute references outside the project folder won't be affected, but all project-relative references (both inside and out) will probably break.
Regardless, there are times when you will want to do this. There are very good reasons to have multiple project documents in the same project folder. See the "Build Location" section in Chapter 17 for some of them.
Xcode 3.2 can open and use projects created with Xcode versions as old as Xcode 2.4. Older project formats might not support all of the current features, and Xcode will warn you if you try to use them. See the next section, "Project Settings," about maintaining backward compatibility with older versions of Xcode.
To work with a project created with Xcode versions 1.5 through 2.3 requires that the project be upgraded. When you open one of these old projects, Xcode presents a dialog box like the one shown in Figure 4-9.
If you choose to upgrade the project, Xcode prompts you to provide the name of a new project document. Note that this is just the name and location of the project document — not the project folder — so it should be saved inside the project folder you are upgrading. Xcode will create a new, modern, project document and open it. The project folder will now have two project documents, as shown in Figure 4-10.
If you only upgraded the project to view it, dispose of the new project when you are done. Otherwise, trash the obsolete project document. It is unlikely that you will want to keep both project documents, unless you plan to maintain them in parallel.
Note
Xcode no longer supports project documents created with versions of Xcode before 1.5, any version of Project Builder (Xcode's ancestor), nor will it import CodeWarrior projects anymore. If you need to start with one of these ancient projects, either download and install Xcode 2.4 or 3.0 and use that as in intermediate step to import/upgrade the old project, or start with a new project and import all of the source files from the old project. It's hard to predict which will be quicker.
Now that you can create projects, take a look at the attributes of the project itself. Choose Project
Here's a brief overview of the General project settings:
The topmost pane shows the location of the project and its source control root directories. Source control and root directories are described in Chapter 21.
The Project Format establishes the earliest version of Xcode that's compatible with this project document. Setting this to Xcode 3.0 means that this project can be opened by Xcode 3.0 and 3.1, but not 2.4. It also means you can't use Xcode features that were added in 3.1 or 3.2 that aren't supported by 3.0. If you lower the format level, there may be features you've already used that aren't compatible with the old version. The Show Conflicts button will describe what features are incompatible.
The next section sets the build locations for this project. Build locations are described in Chapter 17.
The Organization Name is an alternate company name for this project. When you create a new project, Xcode uses the company name in your address book card, as described earlier in "Who's _MyCompanyName_?" To use a different company name in files created just for this project, supply an alternate name here. Clear the field to revert to using your global company name.
The Base SDK defines the default SDK for this project. The Base SDK is described in Chapter 17.
The Rebuild Code Sense Index button flushes and recompiles the project's symbol table, which is used by the editor's auto-completion feature, among others. See the "Code Sense" section of Chapter 7.
The Build tab is where you set the build settings that will apply to everything built by this project.
The Configurations tab organizes named sets of build settings called build configurations. See Chapter 17 for a detailed explanation of build configurations and build settings.
That last tab is for comments. The project, targets, and most other items in the project have a comments field. This is for your personal use. You can keep whatever information you find useful here — Xcode will store the comments in the project document. You might want to include build instructions for other developers, to-do lists, or just a general abstract about the project and why it exists.
In this chapter, you learned how to create new projects. More important, you now know how to choose a project template that will get you started in the right direction. You can open, close, rename, relocate, and switch between multiple projects. Finally, you know where to set the project attributes — although most of those attributes won't make much sense until you get to the targets, build, and source control chapters.
Before a project can build something, the project has to contain something to build. These are the project sources and are the subject of the next chapter.